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Preface 

Purpose 

The purpose of the H P FTAM/ 9000 Programmer's Guide is to introduce 
you to the File Transfer, Access and Management (FTAM) concepts you 
must know to write FTAM applications. Additionally, this guide provides 
example programs and program fragments to illustrate the use of FTAM 
services. 

Audience 

The FI P FTAM/ 9000 Programmer's Guide is for application 
programmers who want to learn to use FTAM and whoare familiar with 
theC programming language. 

Scope 

The FI P FTAM/9000 Programmer's Guideexplains basic FTAM concepts 
and thoroughly explains each FTAM data structure. This guide also 
describes the FTAM functions and their parameters. 

FI P FTAM/9000 runs on FI P OTS/9000, an FI P network product that 
provides a lower-level OSI protocol "stack," in conjunction with an 802.3 
network link. 


Organization 


Chapter 1 


Chapter 2 


Chapter 3 


Chapter 4 


Chapter 5 


Chapter 6 


Chapter 7 


HP FTAM/90000verviewThis chapter provides an 
overview of the standards on which H P based this 
FTAM implementation, and the general concepts you 
should know before writing FTAM applications. 
Reading the conceptual information is vital to 
understanding the terminology used throughout the 
remai nder of the manual. 

Using HP FTAM/9000This chapter describes how to 
start and stop the FTAM system and how to use 
FTAM regimes, functions, parameters, and libraries. 
Additionally, it provides general recommendations 
for programming with FTAM. 

HP FTAM/9000 Data StructuresThis chapter 
describes the structures used by FTAM. Additionally, 
the chapter describes header files, setting bits with 
defined constants, and basic data types. 

Using Support FunctionsThis chapter describes 
the support functions used throughout most 
applications. For example, some support functions 
help you manage memory and translate error codes 
to printable character strings. 

Using High Level, Context Free FunctionsThis 

chapter describes high level, context free (FI LCF) 
functions. H igh level means you can use one function 
instead of several other functions (low level). Context 
free means they are not dependent on the use of 
other functions for their success. 

Managing HP FTAM/9000ConnectionsThis 

chapter describes functions used to establish and 
release FTAM connections. 

Managing and Accessing HP FTAM/9000 

FilesThis chapter describes the functions used to 
manage and access FTAM files after you established 
connections. 
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Chapter 8 

Transferring HP FTAM/9000 DataThis chapter 
descri bes the functions used to transfer data to and 
from FTAM files 

Chapter 9 

Handling ErrorsThis chapter describes 
troubleshooting FTAM, interpreting errors, and 
logging error information. 

Chapter 10 

Example ProgramsThis appendix provides 
complete examples of HLCF functions, creating 

FTAM connections, managing and accessing FTAM 
files, and transferring FTAM data. These programs 
also use the support functions throughout them. 

Chapter 11 

Document Types and Constraint SetsThis 

appendix contains descri bes the file representations 
supported by the various document types and 
constrai nt sets. 

Chapter 12 

Character SetsThis appendix describes the 
available character sets for the H P-UX 
implementation of FTAM. 

Glossary 

The glossary defines terms used throughout the 
manual. 

Index 

The index lists information by topics so that you 
locate necessary information. 

Documentation Guide 

For More 
Information 

Read 

1 installing and 
Configuring H P 
FTAM/9000 

1 nstalling and Administering HP 

FTAM/ 9000 (B1033-90034) 

Troubleshooting HP OSI Troubleshooting Guide(32070-90020) 

FTAM/9000 

FTAM Programming HP FTAM/ 9000 RderenceManual 

(B1033-90004) 
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FTAM Protocol 
Specifications 

I nternational 
Standards ISO 8571 

MAP 3.0 I nterface 
Specifications 

NBS Phase 111 

ACSE 


ASN.l 


BER 


ISO 8571, Information Processing Systems- 
Open Systems I nterconnection - File 
Transfer, Access and M anagement 

I SO 8571,1 nformati on P rocessi ng Systems - 
Open Systems I nterconnection - File 
Transfer, Access and M anagement 

MAP 3.0 Application I nterface Specification 


I mpl ementati on Agreements for Open 
Systems I nterconnecti on Protocols from the 
NBS Workshop for I mplementors of Open 
Systems I nterconnection 

ISO 8649, Information Processing Systems- 
Open Systems I nterconnection - Service 
Ddnnition fortheAssociation Control Service 
Element 

ISO 8824, Information Processing Systems- 
Open Systems I nterconnection - 
Specification of Abstract Syntax Notation 
One (ASN.l) 

ISO 8825, Information Processing Systems- 
Open Systems I nterconnection - 
Specification of Basic Encoding Rules for 
Abstract Syntax Notation One (ASN.l) 
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HP FTAM/9000 Overview 


FileTransfer, Access and Management (FTAM) is an international 
standard for transfer, access, and management of files in an open 
network. H P FTAM/9000 is an H P implementation of this standard; it 
offers the C language programmatic interface defined for MAP 3.0 
FTAM, which in turn, provides you with the following capabilities. 

• Multivendor connectivity 

• Text and binary file transfers 

• File access (record level locate and read) 

• File management, including the foil owing: 

• File creation and deletion 

• File attribute manipulation (read and change) 

• Security mechanisms such as file locking, filestore passwords, and 
concurrency control, and file access control 
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HP FTAM/9000 Overview 

Chapter Overview 


C hapter Overview 

This chapter is an overview of the HP-UX implementation of FTAM. The 
chapter discusses both the standards on which H P FTAM/9000 is based 
and the high-level concepts you should know before writing FTAM 
applications (user programs). The major topics are as follows. 

• The HP-UX I mplementation of FTAM 

• Open Systems I nterconnection (OSI) 

• I SO/I S 8571 FTAM 

• Manufacturing Automation Protocol (MAP) 3.0 

• I mpl ementors Agreements 

• Protocol I mplementation Conformance Statement (PI CS) 

• Conceptual FTAM Overview 

• Virtual Filestore (VFS) 

• Regimes 

• FTAM Communication 

• I nitiators and Responders 

• Application Entities (AEs) 

• Synchronous and Asynchronous Calls 

• File Attributes 

• Document Types 

• Constraints Sets 

• Access Contexts 

• FTAM File Structure Model 


Chapter 1 
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The HP-UX Implementation of FTAM 

The H P-UX implementation of FTAM is compliant with the following 
standards and specifications. 

• Open Systems I nterconnection (OSI) Model 

• I SO/I S 8571 FTAM 

• Manufacturing Automation Protocol (MAP) 3.0 Application Interface 
Specification 

• NBS (NIST) Phase III I mplementors Agreements 

Additionally, H P implemented T1.3, T2.3, A1.3, and M 1.3 profiles from 
the N BS (NI ST) Phase 111 I mplementors Agreements. 

Open Systems Interconnection (OSI) 

The OSI network model defines a standardized network architecture 
that supports connection-oriented communication between devices for all 
vendors. Users of an OSI network can accurately anticipate how other 
network nodes behave. Once a connection is established with a remote 
system, exchange of data is guaranteed. 

The I nternational Standards Organization (I SO) created the OSI model 
to define the actions and services of seven communication functions 
known as the seven layers. Layer seven of this model is the Application 
layer (the layer on which your application program sits). The interface to 
the Application layer describes your view of the network; FTAM resides 
in this seventh layer. The activities below layer seven concern the 
internal workings of the OSI protocols and therefore, are of little concern 
to an application programmer. 

I SO/I S 8571 FTAM 

The international standard (IS) I SO/I S 8571 defines FTAM. This 
standard specifies a virtual filestore, a set of services to manipulate that 
filestore, and a set of rules (protocols) that define how to use the services. 
The formal title of I SO/I S 8571 is "I nformation Processing Systems — 
Open Systems I nterconnection File Transfer, Access and Management.” 
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HP FTAM/9000 Overview 

The HP-UX Implementation of FTAM 


NOTE 


Manufacturing Automation Protocol (MAP) 
3.0 


The Manufacturing Automation Protocol (MAP) 3.0 Specification 
identifies standard protocols for each of the seven OSI layers. The MAP 
3.0 Application I nterface Specification defines the C-language 
programmatic i nterface to each Appl icati on service, i ncl udi ng the HP-UX 
FTAM service. 

NBS (NIST) Implementors Agreements 

The NBS (NI ST) I mplementors Agreements further define 
implementation limitations on I SO/I S 8571 FTAM. H P-UX FTAM 
supports the NBS Phase III minimum requirements, and implements 
many of the NBS options, based on perceived value and compatibility 
with HP-UX. 

There are a number of attributes that H P-UX FTAM does not 
implement. HP-UX FTAM accepts values for these options as input, but 
makes no local use of them. When these options are output, HP-UX 
FTAM provides zero (for integers) or "no value available" (for strings). 
For these options, this document often states that there is "no value 
avail able""" or that HP-UX FTAM responders accept, but ignore the 
value. 

If another implementation is not NBS Phase 11 or Phase III compliant, 
you may still beabletocommunicatewith that implementation. Refer to 
the vendor's Protocol Implementation Conformance Statement (PICS) to 
determine how to set parameters. 


Chapter 1 
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The HP-UX Implementation of FTAM 


Protocol Implementation Conformance 
Statement (PICS) 

The HP-UX FTAM Protocol Implementation Conformance Statement 
(PICS) defines the capabilities of HP-UX FTAM responders. You can use 
PIC Statements to determine if two implementations can communicate. 
Refer to the HP FTAM/9000 Reference Manual on how to obtain the 
HP-UX FTAM PICS. 

HP implements the profiles Al, M1, Tl, and T2. (The foil owing 
references to document types, constraint sets, file access data units 
(FADUs), initiators, responders, and Virtual Filestore are described in 
the "Conceptual FTAM Overview" section.) 


Al Provides for the transferring and accessing of files with 

Unstructured or Flat constraint sets. FTAM-1, FTAM-2, and 
FTAM-3 document types are supported. Al supports reading 
from and writing to a file or a single FADU, locating within 
files, and erasing files. 

Ml Provides for an initiator's management of files within the 

Virtual Filestore, to which access is provided by the responder. 
Management includes creating and deleting a file, and reading 
and changing file attributes. 

Tl Provides for the transferring of entire files with an 

Unstructured constraint set. Both FTAM-1 and FTAM-3 
document types are supported. Tl supports reading from or 
writing to an entire file. 

T2 Provides for the transferring of entire files with an 

Unstructured or Sequential Flat constraint set. FTAM-1, 
FTAM-2, and FTAM-3 document types aresupported. T2 
supports reading from or writing to a file or a single FADU. 
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Overview of FTAM Concepts 

This section takes a high-level approach to explaining concepts you 
should know before writing FTAM applications. This section also refers 
to specific FTAM functions. For detailed information regarding these 
concepts and functions, refer to the Table of Contents for specific 
chapters and sections. 

The Virtual Filestore (VFS) 

A real filestore uses a variety of mechanisms to structure, store, and 
retrieve real files. For example, files on H P-UX systems are stored and 
accessed as a stream of bytes; on other systems files might be stored and 
accessed as fixed- or variable-length records, or in other ways. 

To conceal these storage and access differences, the FTAM specification 
defines a Virtual Filestore, or VFS. The VFS provides a uniform 
interface to all real filesystems. It uses a system-independent model for 
describing files and their attributes. Though it represents real files, it 
masks the system- dependent differences in style and structure. (Refer to 
Figure 1-1.) 

FTAM implementations map the VFS onto a real filestore. The mapping 
function (from the open system to the real system) absorbs the style and 
specification differences. You do not need to know the vendor, operating 
system, or file system with which you want to communicate. You need 
only know a file's complete name and where it is located. (However, you 
may need to read the other vendor's PIC statement.) 
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Figure 1-1 HP-UX FTAM Virtual Filestore (VFS) 

Real File A 
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FTAM Shadow Files 

Because the VFS is generalized, certain VFS concepts have no direct 
correspondence to the HP-UX filesystem. For example, a VFS file might 
have fixed-length records. Such records are not defined for the H P-UX 
file system. 

To provide HP-UX files with FTAM VFS attributes, HP-UX uses two 
files: an actual file and an optional shadow file. 

• The actual file contains the data for the file. The ownership and 
permissions for the file are related to, but distinct from, the FTAM 
attributes for the file. 

• The shadow file contains only the FTAM VFS attributes for the file. 

The actual and shadow files taken together make an "FTAM file."The 
shadow file for an H P-UX file has the same name as the H P-UX file, 
prefixed by For example, the FTAM file named myfile has a 
corresponding shadow file named ,_myfile. Likeall files that begin with a 
period, FTAM shadow files can be listed with the foil owing command: 

$ is -a 

Certain FTAM attributes—such as document type—exist only in the 
shadow file. Other FTAM attributes—such as file name—are mapped to 
normal H P-UX file attributes. Some FTAM attributes—such as access 
control— include a combination of H P-UX file attributes and shadow file 
information. 

The shadow file is not always necessary to read or delete a file. For these 
actions, FTAM uses default attributes. However, whenever FTAM 
creates or modifies a file, it always creates a corresponding shadow file. 


NOTE Other FTAM products from other vendors may implement the VFS using 

methods other than shadow files. 


Shadow File Cautions. Use caution when employing HP-UX 
utilities with FTAM-related files. The following examples illustrate the 
kinds of issues that can arise: 

• If you use mv to rename or relocate an FTAM-related file, the 
corresponding shadow file will not be rename or relocated. 
Subsequent FTAM access tothe file will use default VFS attributes, 
which may or may not apply. 
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• If you use cp to create a new copy of an FTAM-related file, a 
corresponding shadow file will not be created. Subsequent FTAM 
access to the copy will use default VFS attributes, which mayor may 
not apply. 

• Ifyou use chmod or chown to change the HP-UX permissions or 
ownership of an FTAM-related file, the new attributes may conflict 
with the attributes stored in the corresponding shadow file. 
Subsequent FTAM access to the file may have unexpected results or 
cause inconsistencies. 

• Ifyou use rm to remove an FTAM-related file, the corresponding 
shadow file will not be removed. 

Shadow files that are inadvertently severed from their corresponding 
actual files remain as clutter. Furthermore, they could potentially 
interfere with future FTAM operations on files that havethesame name 
as the original actual file. 

Regi mes 

An FTAM transaction is built by calling FTAM functions in steps (or 
nested state sequences) called regimes. A regime is the period during 
which you can issue a specific set of FTAM functions. The regime 
determines the activities that can occur at a given time and therefore, 
creates the rules (protocols) for the FTAM state machine. 

Regimes are nested, in the following order. Applications must pass 
through outer regi mes to gain access to the inner ones. They must also 
exit the regi mes i n proper order, leavi ng the i nner regi mes to gai n access 
to the outer ones. 

• FTAM Regime 

• File Selection Regime 

• File Open Regime 

• Data Transfer Regime 
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Figure 1-2 


FTAM Regime Order 

FTAM Regime 
File Selection Regime 
File Open Regime 
Data Transfer Regime 


FTAM Regime 


File Selection 
Regime 


File Open Regime 


Data T ransfer 
Regime 


The FTAM regime requests FTAM services 
for the connection. The FTAM regime, also 
called the FTAM Association or FTAM 
Initialization regime, is the outermost 
regi me. 

The File Selection regi me references (selects) 
a specific file. You can change and read 
attributes during this regime. 

During the FileOpen regime, a file's contents 
are avail able for access: reading, writing, 
locating, and erasing. 

The Data Transfer regime is the innermost 
regime; it supports the transfer of actual 
data. 


FTAM Communication 

The following sections describe the basic means of FTAM 
communication: initiators, responders, application entities, synchronous 
calls, asynchronous calls, high and low level functions, and context free 
and context sensitive functions. 
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I nitiators and Responders 

As noted earlier, you write a program (user program) to access the FTAM 
interface using a library of functions. FTAM uses the initiator to make 
requests and the responder to service them. (Refer to Figure 1-3.) 


Initiator The initiator submits requests on behalf of you. When you 
submit a request (i.e., call a function), the initiator sends 
your request to a responder. 

• The executable name for an HP-UX initiator isftamjnit (located in 
/opt/ftam/lbin). To use an FTAM function, you must link your 
application with the libmapftam.a library. Theftamjnit process is 
also known as the initiator server provider process (SPP). Refer to the 
"Using FTAM"chapter for information on linking FTAM libraries. 

• Theftamjnit is invoked when you call ft_aeactivation(), and serves 
also as a responder for local FTAM requests. For information on 
ft_aeactivation(), refer to the "Managing FTAM Connections" chapter. 

• Theftamjnit is invoked when you call a high level function with the 
default aejabel (i.e., pointer toa NULL location). For information on 
high level functions, refer to the "Using FTAM” chapter. 


Responder The responder receives and services an initiator's 
request. If applicable, it returns a response. 

• The executable name for an H P-UX responder is ftam_resp (located 
in /opt/ftam/lbin). Theftam_resp is a daemon process that provides 
the interface for the H P-UX filesystem (real filestore) to the FTAM 
VFS. Note that theftam_resp is also known as the responder SPP. 

• One ftam_resp process exists for each active, remote FTAM 
connection. Connections to a local responder do not require an 
invocation of ftam_resp. 

• An ftam_resp daemon process must be active to receive remote 
connection requests. After receiving a request, ftam_resp forks the 
process to create another ftam_resp process, which then processes all 
requests associated with that connection. 


36 


Chapter 1 




HP FTAM/9000 Overview 

Overview of FTAM Concepts 


Figure 1-3 


FTAM Communication Process 



Request Moves Across Network 


Application Entities(AEs) 

An application entity (AE) is a uniquely identified component of your 
application that associates it with theOSI communications network. An 
AE may be an FTAM initiator or responder. 

Before locating, accessing, or manipulating FTAM files, you must 
establish communication (initialize an FTAM regime) with the AE 
(FTAM responder) that services the desired filestore. 

Identify the AE by specifying either the entity's presentation address 
(P_address) or its directory distinguished name (Ae_dir_name). These 
addresses are defined during system configuration and when nodes are 
added to the network. Consult your system administrator for the address 
information. 
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NOTE Refer to the "FTAM Data Structures" chapter for information on the 

P_address and Dir_dn structures. Refer to the I nstalling and 
Administering HP FTAM/9000 manual andtheOSI Troubleshooting 
Guidefor information on the presentation address and directory 
distinguished name configuration. 


Once you establish the FTAM regime, you can access and manipulate 
FTAM files in that filestore. You can perform two types of file act ion son 
the VFS: actions on complete files and file access actions. For example, 
you can create and delete a complete file or access a portion of a file's 
contents. 

Synchronous and Asynchronous Operations 

FTAM functions use two modes of operation: synchronous and 
asynchronous: 


Synchronous Synchronous function calls return only after 
Operations the request is completely processed. Therefore, 
all output information is available when the 
call returns. Make synchronous fundi on calls 
when the results must be processed in a 
specific sequence. 


Asynchronous Asynchronous fundi on calls return as soon as 
Operations ftamjnit validates the request. Processing 
continues on the request. To determine 
whether the request returns successful ly from 
the responder, you must call em_wait(). 
Output information is available only after the 
em_wait()fundion indicates that processing of 
the request has completed. Use asynchronous 
fundion calls when making multiple requests 
and when the order in which results are 
processed does not matter. You can perform 
other operations while an asynchronous 
request is being processed. 
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NOTE Refer to the "H andl i ng E rrors" chapter for i nformati on on checki ng for 

errors on synchronous and asynchronous calls. Refer to the "Using 
Support Functions" chapter for information on using em_wait(). 


File Attributes 

An FTAM file has two distinct parts: its attributes and its contents. 
Attributes describe the file (e.g., size, creator), and areeither file 
attributes or activity attributes: 


File Definethefile properties that are availableto all 

Attributes initiators. File attributes arestored with thefileor 
created with the file. File attributes are an inherent 
part of the file (e.g., size). Some file attributes identify 
structural aspects of the file contents. 


Activity Definethe properties that exist only while a specific 
Attributes FTAM connection is being used. These attributes are 
not part of the file (e.g., file_store_password). 


Document T ypes 

An FTAM document type corresponds to a file type on most systems. I n 
real filestores, common file types include stream text files, 
record-oriented text files, binary files, and directories which contain files. 
These file types are represented by the following FTAM document types: 

• FTAM-1 Unstructured, stream-oriented text files 

• FTAM-2 Record-oriented text files 

• FTAM-3 Unstructured, stream-oriented binary files 

• INTAP-1 Record files 

• NBS-9 Directories, which contain files 

For more information on document types, refer to the "Document Types 
and Constraint Sets" chapter. For information on setting document 
types, refer to the "FTAM Data Structures" chapter. 
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Constraint Sets 

Document types restrict the type of file by specifying constraint sets. 
Constraint sets specify the allowable file structures and the ways in 
which access actions can modify the structure. Constraint sets are either 
Unstructured or Sequential Flat. (Refer to Figure 1-5 and Figure 1-6 
for filestructure information of these two types.) For more information 
on constraint sets, refer to the "Document Types and Constraint Sets" 
chapter. 

Access Contexts 

Constraint sets restrict the type of access contexts available. Access 
contexts specify how the information in the file is accessed. You specify 
access contexts only when reading a file. 

FTAM Document Types 
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Figure 1-5 


FTAM File Structure Model 

The FTAM file model consists of a hierarchical structure (ordered tree) 
containing various levels. 

• Each node in the tree contains a node descriptor. Node descriptors 
reference specific parts of a file. H owever, a node descri ptor may be 
empty. 

• Each node in the tree contains a data unit (DU). This data unit 
contains the actual file contents. 

A file access data unit (FADU) is the smallest unit you can access in 
an FTAM file. A FADU is the complete information content of a subtree 
(i.e., node descriptors and data units). FADUs may be nested and may 
contain several data units. 

The two file structures described by the Unstructured and Sequential 
Flat constraint sets are identified in the following illustrations. 

• An Unstructured constraint set contains one FADU consisting of one 
node descriptor and one data unit. 

FADU Defined by Unstructured Constraint Set 


Root FADU 
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• A Sequential Flat constraint set contains a root FADU with an 
unlimited number of FADUs one level beneath it. 

Figure 1-6 FADU Defined by Sequential Flat Constraint Set 



FADU A FADU B FADU n 
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Before writing HP FTAM/9000 applications, you should understand 
FTAM libraries, regimes, functions, and parameters. 
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C hapter Overview 

This chapter describes how to start and stop FTAM and explains 
information you should know before writing applications. The primary 
sections are as follows. 

• Starting and Stopping the FTAM System 

• Generating FTAM Programs 

• Using Regimes 

• Using Functions 

• Using Parameters 

• General Recommendations 


NOTE This chapter refers to specific functions. For detailed information on a 

function, refer to the Table of Contents for the correct chapter. 


44 


Chapter 2 





Using HP FTAM/9000 

Starting and Stopping the FTAM System 


Starting and Stopping the FTAM System 

The H P OSI Transport Services (OTS/9000) startup procedure 
automatically starts the ftam_resp daemon (HP FTAM responder). You 
may occasionally need to start or stop only the FTAM portion of the 
system. 


NOTE Bringing down the FTAM portion of the HP OSI network system is 

destructive and abruptly terminates any activity using the VFS 
associated with the local responder. 


Using the shutdown option of ftam_resp does not kill user programs or 
ftamjnit processes, though they will encounter unexpected errors when 
you bri ng down the system. You must be superuser to shutdown the 
FTAM responder, as follows. 

$ /opt/ftam/lbin/ftam_resp -shutdown 

To re-start only the FTAM portion of the HP OSI network system, first 
ensure the system is running. Also, executethe ps(l) command toensure 
that no FTAM responder daemons (ftam_resp) are running; if they are, 
execute the above shutdown command. You must be superuser tore-start 
ftam_resp, as follows. 

$ /opt/ftam/lbin/ftam_resp 
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Generating FTAM Programs 

Before using FTAM, you must include header files and link your 
programs with the libmapftam.a and libmap.a libraries. Another 
important library is the lint(l) library used for detecting bugs. 

Header Files 

In your *.c files (source files), you must have the foil owing lines at the 
beginning of your program to include the appropriate header files. 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

libmapftam.a Library 

To access FTAM services, link your application programs with the 
libmapftam.a library. Compileyour programs by executing the foil owing 
command. For information on using the cc command, refer tocc(l) in the 
H P-UX Reference Pages. 


cc [options] -o %<executable> %<files to compile> -lmapftam -lmap -lntl [additional 
libraries] 


lint(l) Library 

A lint(l) library is available for use with the H P-UX programmatic 
interface to FTAM. Using lint(l) saves time by eliminating costly 
debugging effort. Although lint(l) does not detect all bugs, it can find 
some that general testing may not detect. To invoke lint(l), enter the 
following command. 

$ lint -ux filename.c -lmapftam -lmap 

The -ux flags are optional; they remove some unnecessary errors about 
variables that are used, but not defined or some errors that are defined, 
but not used. For more information, refer tolint(l) in the HP-UX 
Reference Pages. 
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Figure 2-1 


Using Regimes 

Regimes define which functions an FTAM application can use at any 
ti me. As an appl i cati on descends the regi mes, you can use specific FTAM 
functions as described in the following figure and sections. The regime 
order is as follows. 

FTAM Regi me Order 


FTAM Regime 
File Selection Regime 
File Open Regime 
Data Transfer Regime 


• FTAM Regime 

• File Selection Regime 

• File Open Regime 

• Data Transfer Regime 

If you use high-level FTAM functions, you do not need to deal with 
regimes; FTAM takes care of these details. 

Regi me Guidelines 

Refer to the foil owing guidelines for working in regimes. 

• You must enter the outer regi mes before enteri ng the i nner regi mes. 
For example, you must enter the File Open regi me before entering the 
Data Transfer regime. 

• You must exit inner regimes before you can exit outer regimes. For 
example, you must exit the File Open regime before exiting the File 
Selection regime. 
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• After exiting an inner regime, you can re-enter the same regime (e.g., 
you can sequentially select several files in the FTAM regime). 

• You can terminate all regimes, no matter how deeply nested, using 
the abort request (ft_abort()). 

Using the FTAM Regime 

The FTAM functions requested during this regime are negotiated 
between the initiator and responder during the protocol exchange. (The 
initiator supplies information which the responder then verifies.) 

Your FTAM application must supply the initiator identity. You may also 
request (i.e., try to negotiate) certain document types (filetypes), 
attribute groups, service cl asses, and functional units. Refer to the 
"FTAM Data Structures" chapter for detailed information regarding 
these negotiated services. 


Document 

Types 


Attribute 

Groups 


Filetypes FTAM-1, FTAM-2, FTAM-3, INTAP-1, 
and NBS-9. FTAM-1 is a text file, FTAM-2 is a 
record-oriented text file, FTAM-3 is a binary file, 
INTAP-1 is a record- oriented binary file, and 
NBS-9 is a directory. 

Organize specific qualities or characteristics to a 
file (e.g., name and size); identify subsets of 
attributes. 


Service 

Classes 


Functional 

Units 


Organize functional units into meaningful groups. 
Each service class identifies mandatory and 
optional functional units. 

Specify which FTAM functions, within the selected 
service class, are allowed. The mandatory and 
optional functional units depend on the service 
class, which must support all selected functional 
unit values. 


The responder verifies requests in one of the foil owing ways. 

• Returns a positive confirmation that it accepts the request with no 
changes. 
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• On ft_connect(), returns a positive confirmation that it accepts the 
request with the given (returned) changes to the initiator's request. 

• Returns a negative confirmation that it does not accept the request. 


Entering the FTAM 
Regime 

I nvoke ft_connect() to 
establish a connection 


Functions Used Within 
the FTAM Regime 

ft_select() moves you to the 
File Selection regime and 
selects a file 

ft_create() moves you to the 
File Selection regime and 
creates, then selects a file 


Exiting the FTAM Regime 

I nvoke ft_rrequest() to 
release the connection and 
move you out of the FTAM 
regime. (Note: You will no 
longer be in a regime, but 
ftamjnit will still be 
activated.) 


Using the File Selection Regime 

Enter the File Selection regime to reference a specific file. You must 
specify a filename. You cannot access a file's contents in the File 
Selection regime; you must enter the File Open regi me to do so. 


Entering the File 
Selection Regime 

I nvoke ft_create() to 
create a new file 

OR 

I nvoke ft_sel ect () to sel ect 
an existing file 


Functions Used Within 
the File Selection Regime 

ft_rattributes() reads file 
attributes 

ft_cattributes () changes file 
attributes 

ft_open() moves you to the 
File Open regime and opens 
a file 


Exiting the File Selection 
Regi me 

I nvoke ft_delete() to move to 
the FTAM regi me and 
permanently remove the file 

OR 

I nvoke ft_deselect() to move 
back to the FTAM regime 
and deselect (but not remove) 
the file 


Using the File Open Regime 

TheFileOpen regime makes the file's contents availablefor reading and 
writing. 
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Entering the File Open 
Regime 

I nvoke ft_open() to access 
a file's contents 


Functions Used Within 
the File Open Regime 

ft_locate() locates a specific 
place (FADU) in a file 
(FTAM-2 files only) 
ft_erase() completely erases 
an entire file 
ft_read() enters the Data 
Transfer regime and 
requests data transfer from 
an FTAM file 
ft_write() enters the Data 
Transfer regime and 
requests data transfer to an 
FTAM file 


Exiting the File Open 
Regi me 

I nvoke ft_close() to move 
back to the File Selection 
regime and close the file to 
further access 


Using the Data Transfer Regime 

The Data Transfer regime is the innermost regime; it supports the 
transfer of actual data. 


E nteri ng the Data 
Transfer Regime 

I nvoke ft_read() to 
request the transfer of 
data from an FTAM file 

OR 

I nvoke ft_write() to 
request the transfer of 
data to an FTAM file 


Functions Used Within 
the Data Transfer Regime 

ft_sdata() sends (writes) data 

ft_rdata() receives (reads) 
data 

ft_edata() ends the sendi ng of 
data 


Exiti ng the Data Transfer 
Regi me 

I nvoke ft_etransfer() to move 
back to the File Open regime 
and end data transfer 

OR 

I nvoke ft_cancel () to move 
back to the File Open regime 
and cancel the transfer of 
data 

OR 

I f you have received a 
cancellation indication, 
i nvoke ft_rcancel () to 
acknowledge the indication 
and move back to the File 
Open regime 
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Using Functions 

FTAM functions may be high level or low level and may be context free or 
context sensitive. Refer to the fol I owi ng sections for i nformati on on these 
function types and for a list of available functions. 

High Level Services (HLS) and Low Level 
Services (LLS) 

FTAM functions are either a high level service (H LS) or a low level 
service (LLS). Both HLS and LLS perform the fol I owing operations. 

• Ensure the input and output data are provided 

• Ensureall mandatory parameters have valid values 

• Ensureall optionally supplied parameters have valid values 

• Provide both synchronous and asynchronous calling modes 


Low Level An LLS is a function that provides the lowest 

Service level of service for the FTAM application 

i nterface. 


High Level An H LS is a function that performs a sequence of 

Service LLS functions, thereby eliminating the need to 

maketheLLS calls individually. For example, the 
HLS ft_fcopy() copies one file to another by 
performing all the necessary steps to do so. The 
ft_fcopy() function establishes connections with 
the source and destination nodes, opens and 
closes the file, reads and writes data, and 
termi nates the regi mes. 
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Context Free (CF) and Context Sensitive (CS) 
Functions 

The term context refers to a dependency on the use of other functions. 


Context Free A function that is context free does not depend on 
prior use of other FTAM functions. You can call a 
context free function at anytime. 


All context free functions are high level services: 
ft_fcopy(), ft_fmove(), ft_frattributes(), 
ft_fcattributes(), and ft_fdelete(). 

Context A function that is context sensitive depends on 

Sensitive prior use of other FTAM functions. You must call 

context sensitive functions in the correct sequence 
as defined by the FTAM protocol. 


All context sensitive functions are low level 
services except for ft_fopen() and ft_fclose(). 


Available Functions 

Figure 2-2 shows the low level FTAM functions available per regime. For 
example, you call ft_select() or ft_create() in the FTAM regime to move to 
the File Selection regime, where you can call ft_rattributes(), 
ft_cattributes(), and ft_open(). To move out of the File Selection regime, 
you call ft_deselect() or ft_delete(). 

Note that you do not have to be in a regime to call those functions shown 
outside the regimes. 
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Figure 2-2 Available FTAM Functions Per Regime 


ft_aeactivation() 


ft_aedeactivation() 

ft_aereset() 

ft_abort() 


FTAM Regime 


File Selection Regime 


ft_read() 

ft_write() 


ft_locate() 

ft_erase() 


ft_open() 


ft_rattribute() 

ft_cattribute() 


ft_select() 

ft_create() 


ft_connect() 


File Open Regime 


Data Transfer Regime 


ft_sdata() 

ft_rdata() 

ft_edata() 

ft_rdataqos() 


ft_etransfer() 

ft_cancel 

ft_rcancel() 


ft_close() 


ft_deselect() 

ft_delete() 


ft_rrequest() 
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The following table briefly describes the FTAM functions. 


Function 

Description 

em_fdmemory() 

Free dynamic memory allocated by 
em_gperror() 

em_ gperrorO 

Translate em_fdmemory(), em_ gperrorO, and 
em_wait() errors (return_codes) to character 
strings 

em_wait() 

Notify you that an asynchronous call 
completed 

ft_abort() 

Abort a connection 

Low level, context sensitive 

ft_aeactivation() 

Activate ftamj nit 

Low level, context free 

ft_aedeactivation() 

Deactivate ftamj nit 

Low level, context sensitive 

ft_aereset() 

Reset ftamj nit 

Low level, context sensitive 

ft_bgroup() 

Designate the beginning of a grouped set of 
functions 

Low level, context sensitive 

ft_cancel() 

Cancel data transfer in progress 

Low level, context sensitive 

ft_cattributes() 

Change file attributes 

Low level, context sensitive 

ft_close() 

Close a file 

Low level, context sensitive 

ft_connect() 

Establish a connection from ftamjnit to a 
responder 

Low level, context sensitive 
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Function 

Description 

ft_create() 

Create a file 

Low level, context sensitive 

ft_delete() 

Delete the currently selected file 

Low level, context sensitive 

ft_deselect() 

Deselect the currently selected file 

Low level, context sensitive 

ft_dfdcb() 

Dynamically free FTAM data control block 
Context sensitive 

ft_didcb() 

Dynamically initialize FTAM data control 
block 

Context free 

ft_edata() 

End a series of data units 

Low level, context sensitive 

ft_egroup() 

Designate the end of a set of grouped functions 
Low level, context sensitive 

ft_erase() 

Erase all or part of a file 

Low level, context sensitive 

ft_etransfer() 

E nd the transfer of data 

Low level, context sensitive 

ft_fcattributes() 

Select and change file attributes, and then 
deselect the file 

H igh level, context free 

ft_fcattri butes_aet() 

Select and change file attributes, and then 
deselect the file 

H igh level, context free 

ft_fclose() 

Close and then deselect or delete a file 

High level, context sensitive 

ft_fcopy() 

Copy a file 

H igh level, context free 

ft_fcopy_aet() 

Copy a file 

H igh level, context free 
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Function 

Description 

ft_fdelete() 

Select and delete a file 

H igh level, context free 

ft_fdelete_aet() 

Select and delete a file 

H igh level, context free 

ft_fdmemory() 

Freedynamic memory allocated by ft_gperror() 
Low level, context sensitive 

ft_fmove() 

Move a file 

H igh level, context free 

ft_fmove_aet() 

Move a file 

H igh level, context free 

ft_fopen() 

Select or create a file, and then open it 

High level, context sensitive 

ft_frattributes() 

Select and read file attributes, and then 
deselect the file 

H igh level, context free 

ft_frattri butes_aet() 

Select and read file attributes, and then 
deselect the file 

H igh level, context free 

ft_gperror() 

Translate returned FTAM error codes to 
character strings 

Low level, context sensitive 

ft _i receiveO 

Receive an abort indication 

Low level, context sensitive 

ftj ocate() 

Locate a specific part of an FTAM-2 file 

Low level, context sensitive 

ft_nwcleared() 

Note when an outstanding resource is cleared 
Low level, context sensitive 

ft_open() 

Open a file 

Low level, context sensitive 

ft_rattributes() 

Read file attributes 

Low level, context sensitive 
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Function 


Description 


ft_rcancel() 

ft_rdata() 

ft_rdataqos() 

ft_read() 

ft_rrequest() 

ft_sdata() 

ft_select() 

ft_write() 


Either acknowledge the end of a data transfer 
in progress 

OR 

Respond to a cancel indication 
Low level, context sensitive 

Receive a block of data 
Low level, context sensitive 

Request transfer of data from a file 
Low level, context sensitive 

Request transfer of data from a file 
Low level, context sensitive 

Release a connection 
Low level, context sensitive 

Send a block of data 
Low level, context sensitive 

Select a file 

Low level, context sensitive 

Request transfer of data to a file 
Low level, context sensitive 
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Figure 2-3 Example Use of Low Level FTAM Functions 
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Typical Applications 

Figure 2-3 on the previous page is an example series of low level FTAM 

functions used within an application. 

• The first column contains major segments (tasks) of a typical FTAM 
application. 

• The second column contains typical low level functions used to 
perform the application tasks. You will probably not use all the 
functions in each box for every application. 
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Using Parameters 

This section discusses parameters to FTAM functions, focussing on the 
input_dcb and inout_dcb parameters. For information on specific 
parameters, determine the function using the parameter; then use the 
Table of Contents to locate the chapter explaining that function. 

Parameters are the mechanisms for exchanging information between 
your application and the FTAM interface. Parameters may be any of the 
following types: 

• Mandatory or Optional 

• I nput to the function, Output from the function 

• Exposed (in thefunction's parameter list) or I nternal (as a component 
of a data structure called a DCB in the parameter list) 

Parameter Order 

Parameters to FTAM functions are organized as follows: 

• I nput parameters precede output parameters. 

• Exposed input parameters precede input DCB parameters. 

• Exposed output parameters follow output DCB parameters. 


NOTE Exposed parameters take precedence over the input_dcb parameters. For 

example, if you specify both the exposed parameter filename and the 
input_dcb->attributes.values.filename on theft_select() function, the 
exposed filename is the one used to select the file. 
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Data Control Blocks 

Data control blocks (DCBs) areC structures used as function parameters 
to pass information between your application and the FTAM interface. 


input_dcb Contains only function input parameters. 

inout_dcb Contains parameters used for both input and output, and 
parameters used for output only. 

Most FTAM functions use both an input_dcb and an inout_dcb. 

inputdcb 

The values used within input_dcb depend on the function requirements. 
If any of the input_dcb parameters are mandatory, you must pass a 
non-N U LL address of an input_dcb; otherwise, you can pass a N U LL 
value. 

You can al locate memory for the i nput_dcb two ways. 

• Allocate the memory yourself (e.g., using mallocO or by using 
variables). 

• Before the request, invoke ft_didcb() to allocate memory for 
input_dcb. After the request completes, invoke ft_dfdcb() to free the 
memory used by input_dcb. 

After the function call returns, you can immediately reclaim or reuse 
memory occupied by input_dcb. 

inoutdcb 

Use the inout_dcb to obtain output information in the user program. 
When passi ng the i nout_dcb to the i nterface, you must pass an address 
that references either a non-NULL or NULL value. 

Except for size, all parameters in the inout_dcb are output parameters. 
Note, however, some output parameters are exposed rather than being 
part of the inout_dcb (e.g., connectionjd on theft_connect() function 
call). 

The size and result fields are always present in the inout_dcb. Other 
inout_dcb fields may be present, depending on the fundi on. 
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NOTE 


For asynchronous calls, you should not access the inout_dcb memory 
from the time the asynchronous call returns SUCCESS until em_wait() 
verifies completion of the request; otherwise, the memory occupied by the 
inout_dcb contains random data. 

You can allocate memory for inout_dcb in three ways. 

1. The recommended method is to have the inout_dcb address reference 
a NULL value when first making the call. 

• By doing so, the FTAM interface allocates the memory necessary; 
thus, you avoid having to anticipate how much memory is 
required. 

• After the FTAM function returns (for asynchronous calls, after 
em_wait() returns SUCCESS), you must call ft_dfdcb() to free the 
memory. 

The next two methods described require you to manually allocate 
memory, and they carry some risk. It can be hard to predict how much 
memory to allocate, and failure to allocate enough can cause a run-time 
error. Consequently, HP encourages programmers to allow the FTAM 
interface to allocate DCB memory. Use one of these last two methods 
only if you have high performance requirements that are seriously 
compromised by the allocation and deallocation time in the first method. 

2. Allocate the memory yourself (e.g., using mallocO or using variables). 
Ensure the size is large enough to hold the inout_dcb structure and all 
data it may rderence. This memory should include a diagnostic list 
that may contain from 0 to 12 elements. You can then pass the 
address of the al I ocated space to the i nterface. 

3. Before the request, invoke ft_didcb() to allocate memory for 
inout_dcb. Ensurethe additional_size parameter is large enough to 
hold the inout_dcb structure and all data it may reference. After 
em_wait() returns SUCCESS, invoke ft_dfdcb() to free the memory 
used by inout_dcb. 
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General Recommendations 

Observe the foil owing recommendations for programming with FTAM: 

• FTAM functions are not re-entrant. Do not call any FTAM function 
within a signal handler. 

• The inout_dcb pointer should reference a NULL value on input. This 
way, you do not have to anticipate the necessary output memory; the 
FTAM i nterface wi 11 allocate it for you. (Remember to later free the 
memory usingft_dfdcb().) 

• You are guaranteed a minimum of 10 local to local (i.e., loopback) 
connections. You might have a maximum of 50 local to local 
connections, depending on the packet sizes. 

• To make troubleshooting easier, always check for errors and record 
the following information: 

• Loop counters and other program-state information. 

• Specific function call that failed 

• I nput parameters passed to the function 

• Function return value 

• inout_dcb->result.return_code 

• inout_dcb->result.vendor_code 

• Log i nstance (upper 16 bits of vendor_code) 

• inout_dcb->diagnostic.error_id 

• inout_dcb->diagnostic.further_details 

• return_string and vendor_string (from ft_gperror() or em_ 
gperrorO) 
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Handling Strings, HP-UX Lines, and FTAM-1 
Lines 


NOTE This section applies to FTAM-1 files only and to strings as they are used 

within low level FTAM calls. 


This section clarifies the meaning of a string, HP-UX line, and FTAM-1 
line. When transferring data with low level calls, you must understand 
FTAM-1 lines. If you are reading or writing local FI P-UX files using low 
level calls, you must understand how to convert between FI P-UX lines 
and FTAM lines. 


String A string is data within or pointed to by the primitive 

field of type struct Ft_data_element. A string may 
contain multipleor partial FTAM lines. 

FIP-UX Line FIP-UX Iines areterminated by LINE FEED %<LF> 
characters (%<LF>is A n' or \ 012'). 

FTAM-1 Line FTAM-1 lines are termi nated by a combination of 
CARRIAGE-RETURN/LINE-FEED %<CR,LF> 
('%<CR>is\r’or \ 015'). 

Since FI P-UX uses %<LF >to represent new lines, you must convert each 
%<LF>to the combi nation %<CR,LF>when writingtoFTAM-lfiles. For 
example, if your application reads an FI P-UX file and subsequently sends 
the data as an FTAM-1 file (using low level FTAM calls), you must 
convert alI instances of %<LF > in the data to %<CR,LF > before sending 
it. 


• AnyFTAM data element you receive uses %<CR,LF>to indicate a 
new line. Consequently, towritesuch data to an FIP-UX file without 
using FTAM, you must writea %<LF>for every %<CR,LF> 
combination. 

• AnyFTAM data element you send must use %<CR,LF>to indicate a 
new line. A single %<LF>character is treated as data. 

If you did not receive data directly from an FTAM function call and if you 
are using FTAM low level calls (e.g., ft_sdata()), you must insert 
%<CR,LF>characters to delimit lines; you will receive them back in 
ft_rdata() output. 
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H P FTAM/9000 functions use data structures to handle information 
consistently and to pass information between cooperating applications. 
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NOTE 


Your understanding of FTAM data structures is vital to your success in 
creating FTAM applications. 
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C hapter Overview 

This chapter describes the structures used for Directory Services, Event 
Management functions (e.g., em_wait(), em_gperror(), and 
em_fdmemory()), and FTAM. Additionally, the chapter describes header 
files, setting bits with defined constants, and basic data types. 
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Header Files 

Two header files, map.h and mapftam.h, contain the necessary FTAM 
structures, constants, and type definitions. Complete header files are 
available online in /opt/ftam/include. 


map.h This header file contains definitions for the constants 
and structures shared by MAP-based OSI services and 
those used the Event Management functions em_wait(), 
em_fdmemory(), and em_gperror(). 

To communicate with remote systems, you must use the 
map.h structures to specify either di rectory 
distinguished names (Ae_dir_name) or presentation 
addresses (P_address). Refer tothe Directory Services 
section for structure information. 

mapftam.h This header file contains the definitions for constants, 
structures, and enumerations specific to FTAM. 
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Using Defined Constants To Set Bits 

Certain structures require that you use defined constants to set bits to 
request specific items like attributes, actions, and concurrency control. 
You request an item by setting a bit to ON (1). Refer to the following 
table for a list of defined constants and their corresponding structures. 


Defined Constants Corresponding Structures 


FT_FA_XXX 

FT_AG_XXX 

FT_AN_XXX 

FT_AC_XXX 

FT_PA_XXX 

FT_FT_XXX 

FT_PM_XXX 

FT_SC_XXX 


Ft_file_actions 
Ft_attribute_ groups 
Ft_attribute_names 
F t_access_control_el ement 
F t_per mi tted_act i ons 
Ft_functional_units 
F t_processi ng_mode 
Ft service class 


• Use the defined constant to set the bits to either ON (1) or OFF (0). 
Setting bits other than those listed results in an error. 

• If needed, set the bit by first defining a variable. Use the appropriate 
defined constant to set the bit you want. 

EXAMPLE 

This example sets the filename and contents_type attributes in the 
variable called attribute_names. 

Ft_attribute_names attribute_names; 

attribute_names = (FT_AN_FILENAME | FT_AN_CONTENT_TYPE); 
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Basic Data Types 


The FTAM interface uses the foil owing data types. These basic types are 
unambiguous typedef synonyms for well-known intrinsic C data types. 

Data Type 

Description 

Corresponding C Data 
Type 

Uint8 

8-bit unsigned integer 

unsigned character 

Unitl6 

16-bit unsigned integer 

unsigned character 

Uint32 

32-bit unsigned integer 

unsigned long 

Sint8 

8-bit signed integer 

char 

Sintl6 

16-bit signed integer 

short 

Sint32 

32-bit signed integer 

long 

Bool 

Logical binary 

unsigned character 

Octet 

8 bits of unformatted 
data 

unsigned character 

Object id 



struct Object_ 

id 


l 

Uint16 
Sint32 

length; 

^element; /* List of 

integers */ 


} ; 


The Objectjd is a widely used map.h structure containing the following 
fields. 

length Number of integers in the*element array, 

^element Pointer to an array of integers. 
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Octetstring 

struct Octet_string 
{ 

Uint32 length; 

Octet_pointer pointer; /* List of Octets */ 

} ; 


The Octet_string is a widely used map.h structure containing the 
following fields. 

length N umber of Octets in the pointer array, 

poi nter Poi nter to a array of Octets. 
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Directory Services Data Structures 

Directory Services holds and provides access to information about objects 
(generally existing in telecommunications and information processing). 
Directory Services stores information in an area collectively known as 
the Directory I nformation Base (Dl B). 

FTAM uses Directory Services to identify responders. One analogy is 
that Directory Services is like a telephone directory that lists responders. 

For communicating with other systems and processes, you need to know 
how to identify yourself and the systems and processes with which you 
want to communicate. FTAM uses Directory Services to obtain the 
presentation addresses (called_presentation_address) for such 
identification purposes. To obtain these addresses, Directory Services 
uses the directory distinguished names (called_dir_name, 
source_dirname, destination_dirname, and dirname) that you provide. 

For information on configuring your directory distinguished names and 
presentation addresses for the OTS/9000 IEEE 802.3 link, refer to the 
OS I Troubleshooting Guide 

Organizing Directory Services 

The Directory Service organization starts at a root entry that is the base 
for all entries. The foilowing list provides possible entries in the required 
order. 

• Country 

• Locality 

• Organization 

• Organizational Unit 

• Application Process (AP) 

• Application Entity (AE) 

Figure 3-1 depicts one possible organizational structure of Directory 
Services. 
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Figure 3-1 


Example Directory Services (X.500) Structure 



Relative 

Distinguished 

Name 

(RDN) 


C=USA 

L=Oklahoma 

0=HP 

OU=Administration 

AP=node_1 

AE=mapftam_init 


Directory 

Distinguished 

Name 

(DDN) 

/C=USA/ 


/C=USA/L=Oklahoma 


/C=USA/L=Oklahoma/ 

0=HP 


/C=US/L=Oklahoma/ 

0=HP/ 

OU=administration 

/C=US/L=Oklahoma/ 

0=HP/ 

OU=administration/ 

AP=node_1 

/C=US/L=Oklahoma/ 

0=HP/ 

OU=Administration/ 

AP=node_1/ 

AE=mapftam_init 
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Using Directory Services 

FTAM uses Directory Services whenever you call ft_connect() or high 
level calls to specify your directory or the directory with which you want 
to communicate. 


Function Parameter 


Identifies 


ft_connect() 


ft_fcopy() and 
ft_fmove() 


called_dir_name Directory distinguished nameof the responder 

process to which you want to connect 

source_dirname Directory distinguished name specifying the 

source filestore 

destination_dirname Directory distinguished name specifying the 

destination filestore 


ft_fcattributes() dirname 

ft_frattributes() 

ft_fdelete() 


Directory distinguished nameof the responder 
process from which you want to change or read 
attributes, or delete a file 
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Ae dir name 


typedef Dir_dn 


*Ae_dir_name; 


Ae_dir_name is the primary structure for setting the directory 
distinguished name when calling ft_connect(), ft_aeactivation(), and all 
high level, context free (H LCF) functions. The embedded structures are 
Dir_dn, Dir_rdn, and Dir_ava ( Figure 3-2). To have the system 
automatically set the Ae_dir_name structure, call convert_ddn; the 
source is in /opt/ftam/demos/cnvrt_addr.c. 

Figure 3-2 Aedirname Structure 


Dir ava 
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Dir dn 


typedef struct Dir_dn /* Directory Distinguished name */ 

{ 

Sint8 n; /*No. of relative dist. names */ 

struct Dir_rdn *rdn; /*Ptr to a sequence of Dir_rdn */ 

} Dir_dn; 


Dir_dn identifies the directory distinguished name. 

• The first field (n) isthe number of relative distinguished names (rdn). 

• The rdn field points to an array of Dir_rdn structures containing 
attribute value assertions (avas). 

• The embedded structures are Dir_rdn and Dir_ava. 

• Each Dir_dn that specifies an application entity (AE) has a 
corresponding P_address stored in the ICS, which provides the 
mapping between the two. 

• TheDir_dn must be exactly the same as the one set during 
configuration. 

EXAMPLE 

I n this example, the directory distinguished name for theftam_resp is as 

follows. Each portion of the name is an rdn (e.g., 0=H P). 

/C=US/0=HP/AP=node_l/AE=ftam_resp 

Figure 3-3 Example Directory Distinguished Name Structure 



Country 
Organization 
Application Process 
Application Entity 
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Dirrdn 

typedef struct Dir_rdn /* Relative distinguished names */ 

{ 

Sint8 n; /^Number of avas */ 

struct Dir_ava *avas; 

} Dir_rdn; 


Dir_rdn identifies the relative distinguished name (Figure 3-4). 

• Each rdn is part of the directory distinguished name. Refer to the 
following example. 

• The first field (n) is the number of attribute value assertions (avas). 

• Each avas points to a Dir_ava structure containing attrjd, 
attr_value, and syntaxjd. 

EXAMPLE 

This example depicts five rdns: three rdns contain one avas each, and 
one rdn (OU) contai ns two avas. 

/C=us/0=hp/L=ca/OU=falc/OU=hawk/AP=nodal/AE=ftam_resp 
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Figure 3-4 


Dir rdn Structure 


Dir ava 



The numbers are for example 
purposes only. The top Dir_rdn 
points to two Dir_ava; the lower 
Dir_rdn points to one Dir_ava. 
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Figure 3-5 


Dir ava 


typedef struct Dir_ava /* Attribute Value assertions */ 
{ 


struct Object_id 

struct Octet_string 

struct Object_id 

} Dir_ava; 


attr_id; 

attr_value; 

syntax_id; /* for future use */ 


Dir_ava isthefinal embedded structure in the Ae_dir_namestructure 
that defines the directory distinguished name (Figure 3-5). 

Each Dir_ava contains the following fields: attrjd (e.g., country), 
attr_value (e.g., USA), and syntaxjd (reserved for future I SO 
extensions). 

Dir ava Structure 


attrjd 


attr value 


syntaxjd 


Dir ava 


length 

element 


Number of the 
Directory Entry 


length 

pointer 

Name of the 
Directory Entry 


length 

element 

n. 

r — — — — n 

i Future ISO Use 1 

L _ _ _ _ J 


Chapter 3 


79 




Figure 3-6 


HP FTAM/9000 Data Structures 

Directory Services Data Structures 


attrjd Theattrjd is an attribute type identifier that is of type 
struct Objectjd. You must set attrjd in one of these two 
ways. 

• Set the first three fields to 2, 5, and 4. Set the fourth 
field to the directory entry identification number. You 
must use these numbers si nee they define a standard 
attri bute type for the protocol. 

2 =joint Jso_ccitt 

5 = attri bute syntax 

4= protocol Objectjd 

n =attrjd or directory entry identification 
number 


• Set only the directory entry identification number 

attr_value The attr_value is of type struct Octet_string. Set 

attr_valueto the name of the country in the Directory 
Services entry. Set the length equivalent to the number 
of characters contai ned i n the attr_val ue poi nter. 

attr id Structure 


attr id 


Directory Entry Identification Number 
length = 4 i 


length 

1 

element 

J 2 i 5 ■ 4 i n 

- . . . 


OR 


length = 1 


Directory Entry Identification Number 


attr id 


length 

element 


n 
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Setting Ae dir name Example 

This example sets the Ae_dir_name structure. 

#include "map.h" 

#include "mapftam.h" 

#include %<stdio.h> 

#include %<malloc.h> 

/* 
k k 

** setup_ddn 

k k 

** DESCRIPTION: 

** This routine assigns valid values to the Ae_dir_name 
** structure. 

k k 
k k 

** PARAMETERS: 

** Outputs: 

** dirname : pointer to the Ae_dir_name structure 

** Ae_dir_name is a pointer to struct 

* * Dir_dn. 

k k 
k / 

void 

setup_ddn(dirname) 

Ae_dir_name *dirname; 


/* 

Initialize all fields of the Ae_dir_name structure. 

Set up: 

"/C=us/0=hp/OU=org_unit/CN=machine_name/CN=ftam_resp" 

k / 

*dirname = (struct Dir_dn *)malloc(sizeof(struct Dir_dn)); 
(*dirname)->rdn=(struct Dir_rdn *)malloc(5*sizeof(struct 
Dir_rdn)); 

(*dirname)—>n = 5; 

/* 

C = us 

The Country attribute id is defined by ISO to be "6". 

k / 

(void)addrdn( & (*dirname)->rdn[0], 6, "us"); 

/* 

0 = hp 

The Organization attribute id is defined by ISO to be 

"10". 

k / 

(void)addrdn( & (*dirname)->rdn[1], 10, "hp"); 

/* 

OU = org_unit 

The Organization Unit attribute id is defined by ISO to be 

"11". 

k / 

(void)addrdn( & (*dirname)->rdn[2], 11, "org_unit"); 

/* 

AP = machine_name 

The Application Process attribute id is defined by ISO to 
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be "3". 

*/ 

(void)addrdn( & (*dirname)->rdn[3], 3, "machine_name"); 

/* 

AE = ftam_resp 

The Application Entity attribute id is defined by ISO to 

be "3". 

*/ 

(void)addrdn( & (*dirname)->rdn[4], 3, "ftam_resp"); 


/* 

*** addrdn 

k k 

** DESCRIPTION: 

** This routine sets up the Dir_rdn structure using the input 
** parameters for values. 

k k 
k k 


** PARAMETERS: 

** Input: 

** att_id : 

** att_value : 

k k 

** Output: 

** rdn : 

k k 
k / 

Sint32 

addrdn(rdn, att_id, 
struct Dir_rdn 
int 
char 


integer value for the attribute id 
character string for the attribute value 


pointer to struct Dir_rdn being set up 


att_value) 

*rdn; 

att_id; 

*att_value; 


/* Allocate the memory for struct Dir_ava 
*/ 

rdn->n = 1; 

rdn->avas = (struct Dir_ava *)malloc(sizeof(struct Dir_ava)); 
rdn->avas->attr_value.pointer = (Octet *)malloc 
(strlen (att_value)*sizeof(Octet)); 
rdn->avas->attr_id.element = (Sint32 *)malloc(sizeof(Sint32)); 
/* 

Set up the attribute id 

*/ 

*(rdn->avas->attr_id.element) = att_id; 
rdn->avas->attr_id.length = 1; 

/* 

Set up the attribute value 

*/ 

memcpy(rdn->avas->attr_value.pointer, att_value, 
strlen(att_value)); 

rdn->avas->attr_value.length = strlen(att_value); 

/* 

The syntax id is for future use 

*/ 

rdn->avas->syntax_id.element = NULL; 
rdn->avas->syntax_id.length = 0; 
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Aejabel 

typedef Uint32 Ae_label 


Aelabel Is Input To These 
Functions 

ft_aedeactivation() 

ft_aereset() 

ft_connect() 

ft_fcattributes() 

ft_fcopy() 

ft_fdelete() 

ft_fmove() 

ft_frattributes() 


Ae label Is Output From 
These Functions 

ft_aeactivation() 

ft_fcattributes() 

ft_fcopy() 

ft_fdelete() 

ft_fmove() 

ft_frattributes() 


Ae_label identifies the ftamjnit activated on a successful 
ft_aeactivation() request. On subsequent ft_connect(), ft_aereset(), and 
ft_aedeactivation() requests, you must specify the aejabel of the 
ftamj nit servicing the user program. 

UseAeJabel on HLCF functions to uniquely identify the desired 
ftamjnit servicing the H LCF call. 

• If the value pointed to by the aejabel is NULL, the interface 
activates ftamj nit for you, returns its aejabel identifier to the user 
program, and then deactivates ftamj nit. 

• If the value is not NULL, the interfaces services the call based on the 
ftamjnit identified by aejabel. 
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Ae title 


typedef union Ae_title 
{ 

struct Object_id ae_object_id; 
struct Dir_dn ae_dir_dn; 
} Ae_title; 


Aetitle Is Input To These Aeti tie Is Output From These 
Functions Functions 

ft_aeactivation() ft_connect() 

ft_connect() 


The my_ae_titie input toft_aeactivation() specifies the ae_titleof the 
ftam_init to activate. Thecalled_ae_title input toft_connect() enables 
you to specify an optional ae_titlefor the responder. 

Both my_ae_title and called_ae_title may be represented as either an 
ae_object_id or ae_dir_dn. However, HP-UX FTAM supports only 
ae_object_id. 

The Ae_title_option value determines whether the Ae_title union takes 
the ae_object_id, ae_dir_dn, or No_value_option form. 

Ae_title carries no semantic value. If not used, set length to zero and 
ae_dir_dn to NULL. 

If you use Ae_title, theobjectjd.element value is set for you to the 
following value: 13 9999 1 ftam_nil_ap_title (7). 


ae_object_id Contains local and remote application entity (AE) 
information. 

ae_dir_dn Contains the directory distinguished name form of 
theAe title. 


84 


Chapter 3 




HP FTAM/9000 Data Structures 
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Aetitleoption 

enum Ae_title_option 

{ 

No_value_option, 

Dir_object_id_option, /* Object_id value obtained from the 

* network or local system directory */ 
User_object_id_option, /* Object_id value supplied by the 

* user */ 

Dir_dist_name_option, /* Use the distinguished name value 

* provided by the my_dir_name 

* or called_dir_name parameter. */ 
User_dist_name_option /* Distinguished name value supplied 

* by the user. */ 

}; 


Ae title option Is Input To 
These Functions 

ft_aeactivation() 

ft_connect() 


Ae title option Is Output 
From These Functions 

None 


Ae_title_option specifies whether to usethe Objectjd or directory 
distinguished name on ft_connect() and ft_aeactivation(). 

The following tables list the supported values for the appropriate 
functions. HP-UX responders return an error if you use an unsupported 
value. 


Aetitleoption 

No_value_option 
D i r_obj ect_ i d_opt i on 


ftaeacti vati on () 

Supported 

Supported 


ft_connect() 

Supported 
Not supported 
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Ae_title_option 


Aetitleoption ft_aeactivation() ft_connect() 

User_object_id_option Supported Supported 

Dir_dist_name_option Not supported Not supported 

User_dist_name_option Not supported Not supported 


No_value_option Ignorethe Ae_titleon ft_aeactivation() and 

ft_connect(); no Ae_title is sent to the 
remote system. 

• For ft_aeactivation(), use my_dir_name. 

• For ft_connect(), use the P_address if it 
exists; otherwise, use called_dir_name. 

D i r_obj ect_i d_opt i on Then et wor k or I oca I system directory 

supplies the Objectjd. For 
ft_aeactivation(), FTAM uses my_dir_name 
to query the Initial Configuration Store 
(I CS) for the Objectjd. 

User_object_id_option You supply the Objectjd value. If you 

specify User_object_id_option, you must 
also specify ae_object_id in the Ae_title. 

Dir_dist_name_option Ignorethe Ae_title. 

• For ft_aeactivation(), use my_dir_name 
as the Ae_title. 

• For ft_connect(), usecalled_dir_nameas 
the Ae_title. 

User_dist_name_option You supply the directory distinguished 

name. If you specify 
User_dist_name_option, you must also 
specify ae_dir_dn in Ae_title union. 
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Apirc 

typedef struct Api_rc 
{ 

Return_code return_code; /* MAP errors */ 

Return_code vendor_code; /* Optional Vendor defined errors */ 
} Api_rc; 


Api_rc (Application I nterface return_code) provides you with error 
information when a function fails. Every function has a parameter of this 
type, usually in its inout_dcband usually defined as the result 
parameter. 
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return_code Specifies the MAP 3.0 error that occurred. These 

errors are listed as defined FTExxx constants. Refer 
to the HP FTAM/9000 Rderence Manual for a list of 
possible errors, their causes, and corrective actions. 

• A return_code value of SUCCESS (zero) indicates 
the request went through the application 
interface, ftamjnit, and responder, and returned 
back to the user program. If the return_code value 
indicates an error (non-zero), the error could be 
detected in any one of these locations. 

• For synchronous calls, the function return value 
and return_code are always identical. 

• For asynchronous calls with a function return 
val ue of SU CCE SS, the return_code i ndicates the 
success or failure of the call. 

• For asynchronous calls, the function return value 
and return_code are identical if the function 
return value of the original call is not SUCCESS. 

vendor_code Contains H P-UX vendor-specific error information 
that describes the error. Note, not all errors return 
vendor codes. 


The upper 16 bits contain the log instance. 


The lower 16 bits define errors that are listed as 
defined FTVxxx constants. Refer to the H P 
FTAM/ 9000 RTerence Manual for a list of possible 
vendor_codes, their causes, and corrective actions. 
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Connectionid 

typedef Uint32 Connection_id; 


Connection id Is Input To 
These Functions 

ft_abort() 

ft bgroupO 

ft_cancel() 

ft_cattributes() 

ft_close() 

ft_create() 

ft_delete() 

ft_deselect() 

ft_edata() 

ft_egroup() 

ft_erase() 

ft_etransfer() 

ft_fclose() 

ft_fopen() 

ft_i receiveO 

ft_l ocate() 

ft_nwcleared() 

ft_open() 

ft_rattributes() 

ft_rcancel() 

ft_rdata() 

ft_read() 

ft_rrequest() 

ft_sdata() 

ft_select() 

ft_write() 


Connection id Is Output 
From These Functions 

ft_connect() 


If ft_connect() is successful, a unique identifier for theconnection returns 
in connectionjd. Thereafter, useconnection_id for any of the functions 
listed in the above table to identify theconnection to the desired filestore. 

Each connectionjd is unique to an application process. 
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Ft access context 


enum Ft_access_context { 

FT_AC_ENUM_DEFAULT = -1, 

FT_HIERARCHICAL_ALL_DATA_UNIT S = 0, 

FT_HIERARCHICAL_NO_DATA_UNITS = 1, 

FT_FLAT_ALL_DATA_UNITS = 2, 

F T_F L AT_ONE_LE VE L_D AT A_UN ITS = 3, 

F T_F L AT_S INGLE_D AT A_UN IT = 4, 

F T_UN S T RU C T URE D_AL L_D AT A_UN ITS = 5, 

FT_UNSTRUCTURED_SINGLE_DATA_UNIT = 6 


} ; 


Ftaccesscontext Is InputTo Ftaccesscontext Is Output 
These Functions From These Functions 

ft_read() None 


Ft_access_context specifies how you want to read the file depending on 
the document type. 

• For FTAM-1, FTAM-3, and INTAP-1 files, you must specify 
FT_U N STRUCTU RED_ALL_DATA_U N ITS. 

• For FTAM-2 files, you must specify either 
FT_F LAT_AL L_DATA_U NITS or 

FT UNSTRUCTURED ALL DATA UNITS. 
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FT_FLAT_ALL_DATA_UNITS For FTAM-2 files, 

specifies that you will 
see both file structure 
and data. 

FT_UNSTRUCTURED_ALL_DATA_UNITS For FTAM-2 files, 

specifies that you will 
see only data. For 
FTAM-1 and FTAM-3 
files, reads the whole 
file. 

FT_AC_ENUM_DEFAULT HP-UX responders 

FT_H IERARCHI CAL_ALL_DATA_UNITS return an error if you 
FT_H IE RARCH ICAL N 0_DATA_U NITS use one of these val ues. 

FT_FLAT_ONE_L EVE L_DATA_UNITS 
FT_FLAT_SI NGLE_DATA_UNIT 
FT UNSTRUCTURED SINGLE DATA UNIT 
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Ft access control 


F taccesscontr ol 

struct Ft_access_control { 

struct Ft_access_control_element *insert_ace; 
struct Ft_access_control_element *delete_ace; 

} ; 


Ftaccesscontrol I s Input To Ftaccesscontrol I s Output 
These Functions From These Functions 

ft_cattributes() None 

ft_create() 

ft_fcattributes() 

ft_fopen() 


Use Ft_access_control to add users to and delete users from the access 
list (Ft_access_control_elements) for a particular file. Both insert_ace 
and delete_ace are linked lists of Ft_access_control_element structures ( 
). This structure specifies user access privileges for the file. 

• If insert_ace is NULL when creating a file (ft_create() and ft_fopen()), 
anyone can access the file. 

• I f you use both insert_ace and delete_ace, H P-UX responders process 
delete ace first. 
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Ft_access_control 


Ft access control element 


struct Ft_access_control_element { 

struct Ft_access_control_element 

Ft_file_actions 

Uint32 

Ft_initiator_identity 
struct Ft_file_passwords 
Ae 

} ; 


‘next; 

action_list; 
conc_access; 
identity; 

*access_passwords; 
*location; 


Ft_access_control_element defines not only whocan access a file, but also 
how they can access it. HP-UX initiators and responders use only the 
identity and action_list fields. You can set values in the other fields if 
another FTAM implementation uses them. 

When interacting with an HP-UX FTAM responder, you can use at most 
three (3) access control elements, one each for user, group, and other. 
Other responders may have different requirements. 


Points to the next Ft_access_control_element structure in the linked 
list. For H P-UX FTAM responders, the maximum number in the 
linked list is three per file. 

list Specifies the allowable actions the designated users can perform on a 

file. An action is present if the corresponding bit is set (ON). 

Change Attribute 

Delete File 

Erase 

Extend 

I nsert 

Read 

Read Attribute 
Replace 

For ft_select() and ft_fopen(), the requested_access parameter must 
be a subset of the values stored in action list. 
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Ft_access_control 


For ft_open(), the processing_mode parameter must be a subset of the 
values stored in action_list. 

Theaction_list isof typeFt_file_actions. Refer tothe"Ft_file_actions" 
section for detailed information. 

The HP-UX implementation of FTAM ignores this value. You can set 
the bits in conc_access, but H P-UX initiators and responders will not 
use it. Other FTAM implementations might. Ifyou are unsure of your 
situation, see the documentation for the other FTAM 
implementation. 


Bits in conc_access correspond tothe allowable actions listed in the 
action_list. Here are the allowed locks, in order, from least to most 
restrictive: 


FileAction Lock 

File Owner Can 

Others Can 

Set by conc_access 

Perform the Action 

Perform the Action 

Not Required 

No 

Yes 

Shared 

Yes 

Yes 

Exclusive 

Yes 

No 

N o Access 

No 

No 


Use the foil owing defined constants to set any combination of 
conc_access bits for file actions. Again, notethat these locks are 
ignored by HP-UX initiators and responders. 


FT_AC_READ_N0TREQ FT_AC_REP LACE_NOACC 

F T_AC_READ_S HARE D FT_AC_EXTEND_NOTREQ 

FT_AC_READ_EXCL F T_AC_E X T END_S HARED 

F T_AC_READ_N0AC C FT_AC_EXTEND_EXCL 

FT_AC_INSERT_NOTREQ F T_AC_E X T E ND_N 0AC C 
F T_AC_INSERT_S HARE D FT_AC_ERASE_NOTREQ 

FT_AC_INSERT_EXCL FT_AC_ERASE_SHARED 

FT_AC_INSERT_NOACC FT_AC_ERASE_EXCL 

F T_AC_RE P LAC E_N0 T RE Q F T_AC_E RA S E_N 0AC C 
FT_AC_REPLACE_SHARED FT_AC_READ_ATTRIB_N0TREQ 
F T_AC_RE P LAC E_E X C L F T_AC_READ_AT TRIB_S HARED 


FT_AC_READ_ATTRIB_EXCL 
F T_AC_READ_AT TRIB_N0ACC 
F T_AC_C HAN GE_AT TRIB_N0TREQ 
F T_AC_CHANGE_ATTRIB_S HARED 
FT_AC_CHANGE_ATTRIB_EXCL 
F T_AC_C HAN GE_AT TRIB_N0ACC 
FT_AC_DELETE_FILE_NOTREQ 
F T_AC_D E LE T E_FILE_S HARED 
F T_AC_D E LE T E_FILE_EXCL 
F T_AC_D E LE T E_FILE_N0ACC 


Specifies the user to whom the access privileges pertain (the "owner" 
in the previous table). For H P-UX initiators and responders, identity 
must have one of the fol I owi ng val ues: user, group, or other. 


The identity is of type struct Ftjnitiatorjdentity. Refer tothe 
"Ftjnitiatorjdentity”section for detailed information. 
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*access_passwords Specifies a user password for each element listed in the actionjist. 

HP-UX initiators and responders do not use this information; 
access_passwords is only used with other FTAM implementations. 

Points to the Ft_file_passwords structure. Refer to the 
"Ft_fiIe_passwords"section for detailed information. 

^location A poi nter of type Ae. HP-UX initiators and responders do not use this 

information; location is only used with other FTAM implementations. 
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Ft account 


typedef char 


*Ft_account; 


Ftaccount Is InputToThese Ftaccount IsOutput From 

Functions These Functions 

ft_connect() None 

ft_create() 

ft_fcattributes() 

ft_fcopy() 

ft_fdelete() 

ft_fmove() 

ft_fopen() 

ft_frattributes() 

ft_select() 

HP-UX responders accept, but ignore, Ft_account. Setting the value to 
NULL is a recommended practice. 
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F tattr i bu tegr ou ps 

typedef Uintl6 Ft_attribute_groups; 


Ft attribute groups Is Input Ftattributegroups Is 

To These Functions Output From These Functions 

ft_connect() ft_connect() 

Ft_attribute_groups specifies the level of support for attributes. 

Attributes are grouped as either kernel, storage, security, or private. 

• The kernel attributes are always present (i.e., you do not negotiate 
them). 

• Attributes within the storage, security, and private groups are valid 
only if you negotiate that group during ft_connect(). 

• Response to an attribute value request (e.g., ft_cattributes()) always 
i ncl udes one of the fol I owi ng items: 

• If you request an unnegotiated attribute, the response includes no 
value available and an error (result_code); may optionally include 
a diagnostic. 

• If theHP-UX responder partially supports the attribute, the value 
(zero (0) for integers; "no value available"for strings) indicates 
that there is no value available. 

• If theHP-UX responder fully supports the attribute, actual values 
are returned. 

• For ft_rattributes() and ft_frattributes(), the attribute_names field 
defaults to indicate all attributes in the attribute_ groups negotiated 
on theft_connect() request. 
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Ft_attribute_groups 

The available attribute groups and their associated attributes are as 
follows: 


Kernel Group Provides basic attributes that are always available, 
filename 

permitted_actions 

contents_type 

Storage Provides additional information on how the file is 

Group stored. 

storage_account * 1 
date_ti me_of_creati on 
date_ti me_of_modificati on 
date_ti me_of_read 
date_ti me_of_attri bute_mod 1 
i denti ty_of_creator 
i dent i ty_of_mod i fi er 1 
i denti tyjaf-reader 1 
identity_of_attri bute_mod 1 
file_avai labi I ity * 
filesize 


future_filesize* 1 

1 When these values are output from H P-UX FTAM 
responders, the val ue (zero (0) for i ntegers; "no val ue 
available" for strings) signifies there is no value for 
the attribute. 
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Security Allows FTAM to enforce what users may operate on 

Group the file and what access each user has. 

access_control 

legal_qualification * 

PrivateGroup ISO does not define the private attributes group. 
private_use* 

* HP-UX responders accept, but ignore, these values. 

To set attribute groups, use the FT_AG_xxx defined constants in the 
mapftam.h file. 

FT_AG_STORAGE 
FT_AG_SECURITY 
FT_AG_PRI VATE 
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Ft attribute names 


Ft attri bute names 

typedef Uint32 Ft_attribute_names; 


Ftattributenames Is I nput Ftattributenames Is 

To These Functions Output From These Functions 

ft_cattributes() None 

ft_create() 

ft_fcattributes() 

ft_fopen() 

ft_frattri butes() 

ft_rattributes() 

This section discusses Ft_attribute_names as a primary structure. For 
information on Ft_attribute_names as it relates to the mask field in 
struct Ft_attributes, refer to the "Ft_attributes" section. 

Ft_attribute_names specifies the attributes you want availablefor each 
file. Ft_attribute_names is the type for the mask field in Ft_attributes. 

• I n ft_create() and ft_fopen(), use Ft_attribute_names to specify which 
attributes you want to set for the newly created file. 

• I n ft_rattributes() and ft_frattributes(), use Ft_attribute_namesto 
specify which attributes you want to read. 

• I n ft_cattributes() and ft_fcattributes(), use Ft_attribute_names to 
specify which attributes you want to change. 


NOTE When using Ft_cattributes or Ft_fcattributes, the attribute_namesfield 

has precedence over attributes.mask. 
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Ft_attribute_names 


Use Ft_attribute_names to set the attribute values you want available 
for each file. Use the FT_AN_xxx defined constants in the mapftam.h file. 

FT_AN_FILENAME 
F T_AN_P E RMIT T E D_AC TI ON S 
FT_AN_CONTENT_TYPE 
FT_AN_STORAGE_ACCT 
FT_AN_CREATE_DATE_TIME 
FT_AN_MOD_DATE_T I ME 
F T_AN_RE AD_D ATE_T I ME 
F T_AN_AT T_MOD_DATE_T I ME 
FT_AN_ID_OF_CREATOR 
F T_AN_I D_OF_MOD IFIER 
F T_AN_I D_OF_READER 
F T_AN_I D_OF_AT T_MOD 
F T_AN_FILE_AVAILABILITY 
FT_AN_FILESIZE 
FT_AN_FUTURE_FILE SIZ E 
FT_AN_ACCESS_CONTROL 
F T_AN_LE GAL_QUAL 
F T_AN_P RI VAT E_U S E 

If you invokeft_rattributes() or ft_frattributes(), HP-UX responders 
return the indication no value available (0) for all partially supported 
attributes. 

If you invoke functions that contain attributes in their input_dcb, H P-UX 
responders accept, but ignore, all partially supported attributes. 
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Ft attributes 


Ft attributes 


struct Ft_attributes { 

Ft_attribute_names mask; 

struct Ft_attribute_values values; 

} ; 


Ft attributes Is Input To Ftattributes IsOutput From 

These Functions These Functions 


ft_cattributes() 

ft_cattributes() 

ft_create() 

ft_create() 

ft_fcattributes() 

ft_fcattributes() 

ft_fopen() 

ft_fcopy() 

ft_select() 

ft_fmove() 


ft_fopen() 


ft_frattributes() 


ft_rattributes() 


ft_select() 


Every file contains attributes that uniquely identify the file and are 
inherent in its existence (e.g., filename). Ft_attributes is the primary 
structurefor setting these attributes. You can change only certain file 
attributes after creating the file, so be careful toset these attributes as 
you want them during ft_fopen() and ft_create(). 
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Attr i butes You C an not 
Change 

permitted_actions 
contents_type 
date_t i me_oif_creat i on 
date_t i me_of_mod ificati on 
date_ti me_of_read 
date_ti me_of_attri bute_mod 
i dent i ty_of_creator 
i dentity_of_modifier 
identity_of_reader 
i dentity_of_attri bute_mod 
filesize 

* With HP-UX FTAM responders, changing these values has no effect. 
Ft_attributes may exist in the input_dcb and inout_dcb. 

mask Themask identifies which attributes are avail able for each 
file. 

values The values identifies the attribute values of the attributes 
specified in the mask. 


Attributes You Can Change 

filename 

storage_account* 

file_availability* 

future_filesize* 

access_control 

I egal_qual ificati on* 

private_use* 
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Ft attributes 


Ftattri bute names 

typedef Uint32 Ft_attribute_names; 


NOTE 


Ft attribute names Is Input 
To These F unctions 

ft_cattributes() 

ft_create() 

ft_fcattributes() 

ft_fopen() 

ft_frattributes() 

ft_rattributes() 


Ftattributenames Is 
Output F rom These 
Functions 

ft_cattributes() 

ft_create() 

ft_fcattributes() 

ft_fopen() 

ft_frattributes() 

ft_rattributes() 


Ft_attribute_names is the type for the mask field in Ft_attributes. 

Use Ft_attribute_names to identify which attributes you want available 
for each file. Use only those values in the FT_AN_XXX defined constants. 
Refer to the previous "Ft_attribute_names" section for more information. 

When using Ft_cattributes or Ft_fcattributes, the attribute_namesfield 
has precedence over attributes.mask. 
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Ft_attributes 


Ftattri buteval ues 


struct Ft_attribute_values { 

Ft_filename 

Ft_permitted_actions 

struct Ft_contents_type 

Ft_account 

Time 

Time 

Time 

Time 

Ft_initiator_identity 

Ft_initiator_identity 

Ft_initiator_identity 

Ft_initiator_identity 

enum Ft_file_availability 

Sint32 

Sint32 

struct Ft_access_control 
Ft_legal_qualification 
struct Octet_string 


filename; 

permitted_actions; 
contents_type; 
storage_account; 
date_time_of_creation; 
date_time_of_modification; 
date_time_of_read; 
date_time_of_attribute_mod 
identity_of_creator; 
identity_of_modifier; 
identity_of_reader; 
identity_of_attribute_mod; 
file_availability; 
filesize; 
future_filesize; 
access_control; 
legal_qualification; 
private_use; 


Use F t_attri bute_val ues to specify the attri bute val ues you want each 
attribute to have. 
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Ft_attributes 

filename Character string that identifies the name of the file. 

permitted_actions Specifies all allowable actions on the file (without specifying who is 
allowed to perform the actions). The permitted_actions is type 
Ft_permitted_actions. 

• For each file, set bits in permitted_actionsfor the actions you are 
al Iowing to be performed. Use these defined constants: 

FT_PA_READ 

FT_PA_I NSERT 

FT_PA_RE PLACE 

FT_PA_EXTEND 

FT_PA_ERASE 

FT_PA_READ_ATTRI BUTE 

FT_PA_CH ANGE_ATTRI BUTE 

FT_PA_DELETE_FI LE 

FT_PA_TRAVERSAL 

FT_PA_REV_TRAVERSAL 

FT_PA_RAN DOM_ORDER 

• Each document type defines certain permitted_actions values, as 
follows: 

FTAM-1, -2, -3,1NTAP-1 FTAM-1, FTAM-3 FTAM-2 
and NBS-9 and INTAP-1 

CH ANGE_ATTRI BUTE ERASE ERASE 

DELETE_FI LE EXTEND INSERT 

READ REPLACE TRAVERSAL 

READ_ATTRI BUTE 

contents_type Specifies the document type of the file; the contents_type is of type 

struct F t_contents_type. Refer to the "F t_contents_type" section for 
a detailed explanation. 
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Ft_attributes 


storage_account Identifies the accountable authority responsible for accumulated file 

storage charges. H P-UX FTAM responders set storage_account so 
that the indication no value available (0) returns if you invoke 
ft rattri butes() or ft_frattri butes(). 

If you invoke functions that contain storage_account in the 
input_dcb, HP-UX responders accept, but ignore, the value. 


date_ti me_of_creation 
date_ti me_of_modificati on 
date_ti me_of_read 
date time of attribute mod* 


i dent i ty_of_creator 
identity_of_modifier* 
identity_of_reader* 
identity_of_attri bute_mod* 


Specifies, respectively, the following dates. 

Date file was created 

Date file was last modified 

D ate fi I e was I ast read 

Date file attributes were last modified 

These val ues are of type Ti me. 

Specifies, respectively, the following user identities: 

User who created the file 

User who last modified the file 

user who last read the file 

User who last modified the file attributes 


* Returns no value available 
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Ft_concurrency_control 


fi I e_avai I abi I ity Thefile_avai I ability is of the foil owing type: 

enum Ft_file_availability { 

FT_IMMEDIATE_AVAIL, 

F T_DE F E RRED_AVAIL 

}; 

For HP-UX responders, you can access the file immediately 
regardless of which value you select. For some implementations, 
file_availabiI ity indicates whether a delay occurs before you can 
access the file. 

filesize Specifies the maximum size (in Octets) of the file. 

future_filesize Specifies the maximum size (in Octets) to which the file may grow if 

you modify or extend it. H P-UX responders return a value of zero 
(no value) on calls toft_rattributes() or ft_frattributes(). 

access_control Defines the conditions under which you and other users can access 

the file. The access_control is of type struct Ft_access_control and 
specifies who can access the file, their access privileges, types of file 
locks, and user passwords. Refer tothe "Ft_access_control" section 
for a detailed explanation. 

legal_qualifications Conveys information about the legal status of the file and its use. 

H P-UX responders return a value of zero (no value) on calls to 
ft_rattributes() or ft_frattributes(). 

private_use HP-UX responders return a value of zero (no value) on calls to 

ft_rattributes() or ft_frattributes(). 


F tconcu r rencycontrol 

struct Ft_concurrency_control { 


enum 

Ft file lock 

read; 

enum 

Ft file lock 

insert; 

enum 

Ft file lock 

replace; 

enum 

Ft file lock 

extend; 

enum 

Ft file lock 

erase; 

enum 

Ft file lock 

read attribute; 

enum 

Ft file lock 

change_attribute; 

enum 

}; 

Ft_file_lock 

delete_file; 
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Ftconcurrencycontrol Is 
Input ToThese Functions 

ft_create() 

ft_fcopy() 

ft_fcattributes() 

ft_fdelete() 

ft_fmove() 

ft_fopen() 

ft_frattributes() 

ft_open() 

ft_select() 


Ft concurrency control Is 
Output From These Functions 

ft_fopen() 

ft_open() 


Concurrency locks define whether users can simultaneously access a file. 
Ft_concurrency_control specifies the type of available concurrency locks 
for each action on a file. 


Change Attribute 
Delete File 
Erase 
Extend 


I nsert 
Read 

Read Attribute 
Replace 


Each value is of type enum Ft_file_lock which specifies the type of 
concurrency locks on a file. 

Setting allowablefile actions and locks requires that you follow a few 
rules. Familiarize yourself with struct Ft_concurrency_control and enum 
Ft_file_lock, and then review the rules in the "Rules for 
Ft_concurrency_control" section. 
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Ft_concurrency_control 


Ftfilelock 


enum Ft_file_lock { 

FT_NOT_REQUIRED 

FT_SHARED 

FT_EXCLUSIVE 

FT_NO_ACCESS 


0 , 

1 , 

2 , 

3 


Ft_file_lock enumerates the type of locks on a file. It is the enumerated 
type for values in struct Ft_concurrency_control. For example, if you 
want to be able to read a file, but you do not want other users to be able 
to, set theconcurrency_control.read lock to FT_EXCLUSI VE. 


File Action Lock Set by 
Ftfilelock 

Owner May Perform The 
Action 

Others May Perform The 
Action 

Not Required 

No 


Yes 

Shared 

Yes 


Yes 

Exclusive 

Yes 


No 

N o Access 

No 


No 


Rules for Ft concurrency control 

• You may wish to set concurrency control to N U LL wherever it exists 
as a parameter. This way, the responder uses its own default values. 
H P-UX responders use the defaults specified in the NBS Phase 111 
agreements. The values used by a responder during the open regime 
are returned in the inout_dcb of theft_open() and ft_fopen() calls. 

• If you use concurrency control (concurrency control is not NULL), you 
must specify a lock for each file action. 

• For those actions that are available (because you requested them in 
the requested_access parameter), the applicable locks are 
FT_SHARED and FT_EXCLUSIVE. 

• For those actions not available (because you did not request them in 
the requested_access parameter), the applicable locks are 

FT_N0_ACCESS and FT_NOT_REQUIRED. 
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• The ft_open() concurrency control must be identical to—or more 
restrictive than—the ft_select() concurrency control; it may not be 
less restrictive 


CAUTION When a system has an N F S-mounted file system , two different files can 

have the same device id and inode number. If both are used by FTAM 
concurrently, the locks applied toonefilecould interfere with a select or 
open operation on the other file. 

Furthermore, files on NFS-mounted filesystems are visible on more than 
one host. Therefore, it is possiblefor FTAM to have locks on the same file 
from two different hosts. While each host may believe it has exclusive 
access to the file, in fact both hosts have concurrent access. 


Table 3-1 Concurrency Control: Default Settings 


1 n the 

SELECT 

regime: 

For actions not set in 
the requested_access 
parameter, 
corresponding locks 
default to: 

For each action set in 
the requested_access 
parameter, if the 
action is read or 
read_attribute, the 
corresponding lock 
defaults to: 

For each action set in 
the requested_access 
parameter, otherwise, 
the corresponding 
lock defaults to: 


Not Required 

Shared 

Exclusive 


I n the OPEN By default, all locks in the OPEN regime are set to the lock value for the 
regime: current SELECT regime, either the defaults (above) or user-selected. 
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F tcontentsty peel ement 

struct Ft_contents_type_element { 

struct Ft_contents_type_element *next_element; 

struct Ft_contents_type contents_type; 

} ; 


F tcontentsty peel ement I s F tcontentsty peel ement I s 

Input To These Functions Output From These Functions 

ft_connect() ft_connect() 

On input, Ft_contents_type_element is the requested document types 
per connection; on output, it is a linked list of allowable (negotiated) 
document types per connection. Use Ft_contents_type_element tospecify 
up to three document types: FTAM-1, FTAM-2, and FTAM-3. 


*next_element Points to the next Ft_contents_type_element 
structure in the linked list. H P-UX responders 
accept up to three Ft_contents_type_element 
structures; after three, HP-UX responders ignore 
the value. 


HP-UX responders accept only FTAM-1, FTAM-2, 
and FTAM-3 document types; if you request any 
other document type, H P-UX responders remove 
the element from the response list. 

contents_type Per connection, specify one contents_typefor each 
document type you want to manipulate (transfer, 
access, or manage). 
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Ft_contents_type 


F tcontentsty pe 

struct Ft_contents_type { 

enum Ft_contents_form contents_form; 

union Ft_contents_info contents_info; 

}; 


Ft_contents_type specifies the allowable document type for a particular 
file. 

Ft_contents_type is the type for the contents_type field i n struct 
Ft_contents_type_element (a linked list of allowable document types per 
connection). This structure is also nested within the values field, which is 
of type struct Ft_attributes. 


contents form 


contents info 


Specifies the contents_type form as a known or 
unknown document type. 

Specifies the exact document type. 


F tcontentsfor m 


enum Ft_contents_form { 

FT_DOCUMENT_TYPE = 0, 
F T_AB S_CON_S E T_P AI R_F ORM = 1, 
FT_CONTENTS_UNKNOWN = 2 


Ft_contents_form specifies whether contents_type is a known or 

unknown document type. 

• For all functions that usethe Ft_contents_type, (except ft_fopen() and 
ft_open()), you must specify FT_DOCUMENT_TYPE. 

• HP-UX FTAM does not permit you to usethe value 
FT_ABS_CON_SET_PAI R_FORM. 

• Specify FT_CONTENTS_UNKNOWN on ft_open() and ft_fopen() if 
you do not know the document type; the document type is returned in 
theinout deb. 
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Ft_contents_type 


F tcontentsi nfo 


union Ft_contents_info { 

struct Ft_document_type document; 

struct Ft_abs_con_set_pair abs_con_set_pair; 

}; 


Ft_contents_info specifies the document type. 

• If you specified FT_DOCUMENT_TYPE in Ft_contents_form, specify 
the document. 

• If you specified FT_CONTENTS_UN KNOWN in Ft_contents_form, 

Ft_contents_info is ignored. 

• As noted under Ft_contents_form, H P-UX responders do not permit 
use of the abs_con_set_pair structure. 

F tdoc u men tty pe 

struct Ft_document_type { 

struct Object_id name; 

char ‘parameters; 


Ft_document_type defines the document type structure of the file. For 
detailed information (e.g., restrictions imposed) on document types, refer 
to the "Document Types and Constraint Sets" chapter. 
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^parameters 


HP FTAM/9000 Data Structures 

Ft_contents_type 


Specifies the name of the document type and is of the following type struct 
Objectjd (from map.h). 

struct Object_id 

{ 

Uintl6 length; 

Sint32 *element; /* List of integers */ 

}; 

• Set the length field to 5 for all document types except NBS-9; for 
document type N BS-9 set length to 6. 

struct Ft_contents_type cont_type; 

cont_type.contents_info.document.name.length = 5; 

• Specify thedocument_type name by setting the element array as follows: 

1 0 8571 5 1 for FTAM-1 document type 
1 0 8571 5 2 for FTAM-2 document type 
1 0 8571 5 3 for FTAM-3 document type 
1 2 392 10 2 1 for INTAP-1 document type 
1 3 14 5 5 9 for N BS-9 document type 

This example sets the Ft_contents_type structure for an FTAM-3 file. 
Thedocument_type name for FTAM-3 is 1 0 8571 5 3 


struct Ft_contents_type 


cont_type; 


struct Ft_dt_ftam_3 


*ftm_3; 


cont_type.contents_form = FT_DOCUMENT_TYPE; 

ftm_3 = (struct Ft_dt_ftam_3 *)malloc(sizeof(struct Ft_dt_ftam_3)); 
cont_type.contents_info.document.name.element = 

(Sint32 *)malloc(5*sizeof(Sint32)) ; 


ftm_3->string_length = 512; 

ftm_3->significance = FT_SS_NO_SIGNIFICANCE; 

cont_type.contents_info.document.parameters = (char *)ftm_3; 


cont_type.contents_info.document.name.length = 5; 
cont_type.contents_info.document.name.element[0]=1; 
cont_type.contents_info.document.name.element[1]=0; 
cont_type.contents_info.document.name.element[2]=8571; 
cont_type.contents_info.document.name.element[3]=5; 
cont_type.contents_info.document.name.element[4]=3; 

Generic pointer to one of the foil owing structures: Ft_dt_ftam_l, 
Ft_dt_ftam_2, Ft_dt_ftam_3, Ft_dt_intap_l, or Ft_dt_nbs_9. 
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Ft_contents_type 


Ftdtftaml. 


struct Ft_dt_ftam_l 


enum Ft_class 
Uint16 

enum Ft_string_significance 


class; 

string_length; 

significance; 


• The class must be FT_CL_I A5_STRI NG or 
FT_CL_GENERAL_STRI NG. 

• The string_length supported by responders must be at least 0 to 134; 
for HP-UX responders, stringjength is unlimited. 

• The significance must be FT_SS_NO_SI GNI FI CANCE. 

Ft_dt_ftam_2. 

struct Ft_dt_ftam_2 
{ 

enum Ft_class 
Uint16 

enum Ft_string_significance 

}; 


class; 

string_length; 

significance; 


• The class must be FT_CL_GRAPH I C_STRI N G. 

• The string_length supported by responders must be at least 0 to 134; 
for HP-UX responders, stringjength is unlimited. 

• The significance must be FT_SS_NO_SI GNI FI CANCE. 

Ft_dt_ftam_3. 

struct Ft_dt_ftam_3 
{ 

Uintl6 string_length; 

enum Ft_string_significance significance; 

} ; 


• Ft_dt_ftam_3 defaults to FT_CL_OCTET_STRI NG. 

• The stringjength supported by responders must be at least 0 to 512; 
for HP-UX responders, stringjength is unlimited. 

• The significance must be FT_SS_N0_SI GNIFI CANCE. 
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Ft_contents_type 


Ftdtintapl. 

struct Ft_dt_intap_l 
{ 

Uintl6 record_length; 

enum Ft_string_significance significance; 

} ; 


• Ft_dt_intap_l defaults to FT_CL_OCTET_STRI N G. 

• The recordjength is unlimited. 

• The significance must be FT_SS_VARI ABLE or FT_SS_FIXED. 

Ft_dt_nbs_9. 

struct Ft_dt_nbs_9 
{ 

Ft_attribute_names mask; 

} ; 


• mask is a 32-bit unsigned integer. Use any of the FT_AN_xxx defined 
constants to set bits in the mask. See Ft_attribute_names for details. 

• This parameter is used only on a call toft_open(). An NBS-9 
document (a directory) can only be opened for reading. Therefore, any 
attribute names you supply on theft_open() call specify the attributes 
you will receive for the files in the directory. 

• If you omit this parameter, the responder will supply default 
attributes. HP-UX FTAM responders will return all attributes by 
default. 
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Ft data unit 


Ftdataunit 


struct Ft_data_unit { 

struct Ft_data_unit 
enum Ft_structure_id 
union { 

struct Ft_data_element 
struct Ft_node_descriptor 
} data; 

} ; 


‘next; 

structure_id; 

*data_element; 
‘node; 


Ft_data_unit Is Input To Ft data unit Is Output From 
These Functions These Functions 

ft_sdata() ft_rdata() 

Ft_data_unit is a linked list of data units (maximum 14 data units per 
call). Each data unit contains the data that FTAM manipulates (Figure 
3-8). 

The responder uses Ft_data_unit to return data when you call ft_rdata(). 

For variable and fixed data, data element boundaries are preserved. You 
receive the exact sequence of data elements that existed in the original 
file. 

If Ft_string_significance is FT_SS_NO_SIGNI FICANCE, data element 
boundaries are ignored. Up until the final data element, the responder 
returns the maximum stringjength allowed per data element. The final 
data el ement contai ns the remai ni ng data. 
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Ft_data_unit 

Figure 3-8 FtdataunitcStructure 

Up to 14 struct Ft_data_unit per call 


Ft data unit Ft_data_unit Ft data unit 



NOTE To understand Ft_data_unit, you should be familiar with the concepts 

FADU, data unit, data element, and node descriptor. Refer to the "FI P-UX 
FTAM Overview" chapter for descriptions. 


*next Points to the next Ft_data_unit structures in the 

linked list. The maximum is 14. 


structurejd Specifies which structure in the data union is 
applicable. 

data The data union contains *data_element and *node. 

The value you choose in Ft_structure_id dictates 
which structure you choose in the data union. 

• The *data_element is of type struct 
Ft_data_element and contains the actual data. 

• The *node is of type struct Ft_node_descriptor 
and indicates a new FADU. 


Ftstructureid 


enum Ft_structure_id { 

F T_D AT A_UN IT = 0, 
FT_NODE_DESC = 1, 
FT_ENTER_SUBTREE = 2, 
FT_EXIT_SUBTREE = 3, 
FT_DATA_END_IND = 4, 
FT_CANCEL_IND = 5 


} ; 
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Ft data unit 


Ft_structure_id specifies which structure in the data union is applicable 
(Ft_data_element or Ft_node_descriptor) or it specifies the end or 
cancellation of data transfer (on output only). 


FT_DATA_UNIT Use FT_DATA_U N IT to send actual data. FT_DATA_UNIT 

dictates that you choose data_element in the data union. 

FT_NODE_DESC Use FT_NODE_DESC only for FTAM-2 document types to begin 

a new FADU. FT_NODE_DESC dictates that you choose node in 
the data union. 

FT_ENTER SUBTREE HP-UX responders return an error if you use either of these 

FT_EXIT_SUBTREE values. 

FT_DATA_E N D_l N D When usi ng ft_rdata(), FTAM returns FT_DATA_E N D_l N D i n 

inout_dcb.data_unit->structure_id to i ndicate data transmission 
is complete. 

FT_CANCEL_IND If an error occurs when transferring data, FTAM returns 

FT_CANCEL_IND in inout_dcb.data_unit->structure_id to 
indicate data transmission is cancel led. To acknowledge the data 
transfer was cancelled, you must issueft_rcancel() toexit the 
DataTransfer regime. 

F tdatael ement 

struct Ft_data_element { 

enum Ft_prim_type { 

FT_DE_BOOLEAN 
FT_DE_INTEGER 
FT_DE_BIT_STRING 
FT_DE_OCTET_STRING 
FT_DE_NULL 
FT_DE_IA5_STRING 
FT_DE_UTC 
FT_DE_TIME 

FT_DE_GRAPHIC_STRING 
FT_DE_VISIBLE_STRING 
FT_DE_GENERAL_STRING 
FT_DE_FLOATING_POINT 
FT_DE_UL_FLOAT 
FT_DE_UL_INTEGER 
FT_DE_ATTRIBUTES 
FT_DE_RECORD_END 
FT_DE_RECORD_CONT 

} prim_type; 


= 1 , 

= 2 , 

= 3, 

= 4, 

= 5, 

= 22 , 

= 23, 

= 24, 

= 25, 

= 26, 

= 27, 

= 100 , 
= 101 , 
= 102 , 
= 200 
= 201 
= 202 
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union Ft_primitive { 

Bool 

Sint32 

struct Bit_string 

struct Octet_string 

struct Octet_string 

Time 

Time 

char 

char 

struct Octet_string 
double 

struct Octet_string 
struct Ft_ul_floating_point 
Sintl6 

struct Bit_string 
struct Octet_string 
} ul_floating_point; 
struct Ft_attributes 
struct Octet_string 
struct Octet_string 
} primitive; 

} ; 


boolean; 

integer; 

bit_string; 

octet_string; 

ia5string; 

utc; 

time; 

*graphic_string; 
*visible_string; 
general_string; 
floating_point; 
ul_integer; 

{ 

sign; 
mantissa; 
exponent; 

attributes; 
record_end; 
record_cont; 


Set Ft_data_element if you specified FT_DATA_UNIT in 
Ft_structure_id. 

Ft_data_element contains an enum Ft_prim_typethat indicates which 
primitive is relevant in union Ft_primitive (Figure 3-9). 

Figure 3-9 Ftdataelement Structure 


Up to 14 struct Ft_data_unit per call 



prim_type The prim_type specifies which field in the primitive union to select. Only a 
subset is valid for each document type: 
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Ft_data_unit 

FTAM-1 

I A5_STRI NG 
GENERAL_STRING 
GRAPHIC_STRING 
GENERAL STRING 


FTAM-2 

GRAPHIC_STRING 
GENERAL STRING 


FTAM-3and INTAP-1 NBS-9 

OCTET STRING ATTRIBUTE 


primitive The primitive is the specific unit that contains actual data. Set primitive to the 
value specified by prim_type. Seethe previous table. Note that the maximum 
string length is 7168 (7K) octets. 


EXAMPLE: This example sets a data_element for FTAM-2 document type. 

struct Ft_data_unit data_unit; 


data_unit.next = NULL; 

data_unit.structure_id = FT_DATA_UNIT; 

data_unit.data.data_element = (struct Ft_data_element *) 
malloc(sizeof (struct Ft_data_element)); 


data_unit.data.data_element->prim_type = FT_DE_GRAPHIC_STRING; 
data_unit.data.data_element->primitive.graphic_string = 

"This example shows data in a data element;" 


Ft node descri ptor 

struct Ft_node_descriptor { 

Ft_fadu_name fadu_name; 

Uintl6 arc_length; 

Bool data_exists; 

} ; 


Set Ft_node_descriptor if you specified FT_NODE_DESC in 
Ft_structure_id (Figure 3-10). 

Use Ft_node_descriptor only with FTAM-2 document types to begin a 
new FADU. 
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Figure 3-10 Ft node descriptor Structure 


Up to 14 struct Ft_data_unit per call 



fadu name 


arcjength 


data exists 


HP-UX responders accept, but ignore, thefadu_namefield. HP 
recommends you set the fadu_name.length to zero and 
fadu_name.pointer to NULL. 

You must set arcjength to 1 since FTAM-2 is confined by the 
sequential flat constraint set (which has only one hierarchical level). 

You must set data exists toTRUE since all FAD Us must contain data. 


EXAMPLE: This example sets the node_descriptor for an FTAM-2 document type. 


struct Ft_data_unit data_unit; 

data_unit.next = NULL; 

data_unit.structure_id = FT_NODE_DESC; 
data_unit.data_node = (struct Ft_node_descriptor *) 
malloc(sizeof (struct Ft_node_descriptor) ) ; 
data_unit.data.node->fadu_name.length = 0; 
data_unit.data.node->fadu_name.pointer = NULL; 
data_unit.data.node->arc_length = 1; 
data_unit.data.node->data_exists = TRUE; 


NOTE Creating the Ft_data_unit linked lists for FTAM-2 document types 

requires that you follow a few rules. First, familiarize yourself with the 
Ft_node_descriptor structure. Then read the next section, which 
describes the necessary rules. 
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Rules for Ftdataunit Linked Lists (FTAM-2 
Only) 

The following rules apply to Ft_data_unit linked lists for FTAM-2 

document types only. 

• If you have an empty file, you must begin the linked list with a node 
descriptor (not a data element). 

• If a file already contains data, you may or may not have a node 
descriptor, depending on whether you are starting a new FADU. 

• Do not immediately follow a node descriptor with another node 
descriptor. 

You may, however, follow a data element with another data element 
(i.e., node descriptors may have multipledata elements). 

• You may submit an ft_sdata() request containing only a node 
descriptor, though you must follow it with an ft_sdata() request that 
starts with a data element. 

• Do not use more than one node descri ptor per ft_sdata() request. 

• You must set node.arcjength to 1. 

• You must set data exists toTRUE since FADUs must contain data. 
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Ftdcbtype 

enum Ft_dcb_type { 


FTiAeactivation 

= 

0, 

FToAeactivation 

= 

1, 

FTiAedeactivation 

= 

2, 

FToAedeactivation 

= 

3, 

FTiConnect 

= 

4, 

FToConnect 

= 

5, 

FTiRelease 

= 

6, 

FToRelease 

= 

7, 

FTiAbort 

= 

8, 

FToAbort 

= 

9, 

FTiAereset 

= 

10, 

FToAereset 

= 

11, 

FTilreceive 

= 

12, 

FToIreceive 

= 

13, 

FToNwcleared 

= 

99, 

FTiFCopy 

= 

100 

FToFCopy 

= 

101 

FTiFMove 

= 

102 

FToFMove 

= 

103 

FTiFDelete 

= 

104 

FToFDelete 

= 

105 

FTiFRattributes 

= 

106 

FToFRattributes 

= 

107 

FTiFCattributes 

= 

108 

FToFCattributes 

= 

109 

FTiFOpen 

= 

110 

FToFOpen 

= 

111 

FTiFClose 

= 

112 

FToFClose 

= 

113 

FTiSelect 

= 

200 

FToSelect 

= 

201 

FTiDeselect 

= 

202 

FToDeselect 

= 

203 

FTiOpen 

= 

204 

FToOpen 

= 

205 

FTiClose 

= 

206 

FToClose 

= 

207 

FTiCreate 

= 

208 

FToCreate 

= 

209 

FTiDelete 

= 

210 

FToDelete 

= 

211 

FTiReadattributes 

= 

212 

FToReadattributes 

= 

213 

FTiChangeattributes 

= 

214 

FToChangeattributes 

= 

215 

FTiRead 

= 

216 

FToRead 

= 

217 

FTiWrite 

= 

218 


The Ft_dcb_type data type is continued on the next page. 
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This Ft_dcb_typedata type is continued from the previous page. 


FToWrite 

= 

219 

FTiErase 

= 

220 

FToErase 

= 

221 

FTiLocate 

= 

222 

FToLocate 

= 

223 

FTiSData 

= 

224 

FToSData 

= 

225 

FTiRData 

= 

226 

FToRData 

= 

227 

FTiDataEnd 

= 

228 

FToDataEnd 

= 

229 

FTiTransEnd 

= 

230 

FToTransEnd 

= 

231 

FTiBGroup 

= 

232 

FToBGroup 

= 

233 

FTiEGroup 

= 

234 

FToEGroup 

= 

235 

FTiCancel 

= 

236 

FToCancel 

= 

237 

FTiRCancel 

= 

238 

FToRCancel 

= 

239 


Ft dcb typelsInputToThese Ft dcb type Is Output From 

Functions These Functions 

ft_didcb() None 

Ft_dcb_type identifies the type of data control block (DCB).The 
ft_didcb() function then initializes and allocates memory for the fixed 
parameters within the specified DCB. 

• A lowercase i after FT indicates an input_dcb. 

• A lowercaseoafter FT indicates an inout deb. 
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F tdel eteacti on 

enum Ft_delete_action { 

FT_DELETE_FILE = 0, 

FT_DONT_DELETE_FILE = 1 

}; 


Ftdeleteaction Is Input To Ftdeleteaction IsOutput 
These Functions From These Functions 

ft_fclose() None 

Ft_delete_action specifies whether to delete a file or only deselect it on an 
ft_fclose() function. 


FT_DELETE_FI LE Closes, deselects, and then deletes the 

file. 

FT_DONT_DELETE_FI LE Closes and deselects, but does not delete 

the file. 
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F tdel eteover wr i te 

enum Ft_delete_overwrite { 

FT_RECREATE_FILE = 0, 

FT_DONT_RECREATE_FILE = 1 

}; 


Ftdeleteoverwrite Is I nput FtdeleteoverwritelsOutput 
To These Functions From These Functions 

ft_fcopy() None 

ft_fmove() 

Ft_delete_overwrite specifies whether or not to copy over (ft_fcopy()) or 
move over (ft_fmove()) an existing file. 


FT_RECREATE_FI LE Copy or move the source file over the 

existing destination file. 

FT_DONT_RECREATE_FI LE Do not copy or move the source file 

over the existing destination file; the 
function fails and you receive an 
error. 
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Ft_diagnostic 


F ^diagnostic 

struct Ft_diagnostic { 


struct 

Ft_diagnostic 

*next; 

enum 

Ft_diag_type 

diag_type; 

Uintl6 


error_id; 

enum 

Ft_entity_ref 

error_observer; 

enum 

Ft_entity_ref 

error_source; 

Uintl6 


suggested_delay; 

char 


*further_details 


Ftdiagnostic Is Input To 
These Functions 


Ft diagnostic Is Output 
From These Functions 


ft_abort() 

ft_cattributes() 

ft_cancel() 

ft_close() 

ft_connect() 

ft_edata() 

ft_create() 

ft_rcancel() 

ft_delete() 

ft_deselect() 


ft_edata() 


ft_erase() 


ft etransferO 


ft_fcattributes() 


ft_fclose() 


ft_fcopy() 


ft_fdelete() 


ft_fmove() 


ft fopen() 


ft_frattributes() 


ft_ireceive() 


ft_locate() 


ft open() 


ft_rattributes() 


ft_sdata() 


ft_select() 


ft_rdata() 


Ft_diagnostic provides additional information for I SO-specific errors. 
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Ft_diagnostic 


Figure 3-11 


*next 

diag_type 

error_id 

error observer 


Thefurther_details field may vary across different vendor responders. 
Refer to the H P FTAM/ 9000 Reference Manual for a list of H P-UX 
diagnostic messages, their probable causes, and possible corrective 
actions. 


Ftdiagnostic Structure 

Ft_diagnostic 


Up to 12 struct Ft_diagnostic 



Linked list of Ft_diagnostic structures; maximum number is 12. 
Specifies the kind of I SO error that occurred. 

Specifies the integer representing the I SO error that occurred; defined 
in f_error.h. 

Specifies the entity that detected the error. 
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Ft_diagnostic 


error_source Specifies the entity in which the error occurred. 

suggest ed_del ay Specifies the amount of time to wait before attempting recovery if the 

Ft_diag_type is FT_TRANSI ENT. HP-UX responders do not use this 
field; they never return a diag_typeof FT_TRANSI ENT. 

*further_details Provides additional information (a text message) about the cause of 
the error. This information may vary among different vendor 
responders. 

Ftdiagtype 

enum Ft_diag_type { 

FT_INFORMATIVE = 0, 

FT_TRANSIENT = 1, 

FT_PERMANENT = 2 

} ; 

Ft_diag_type specifies the kind of I SO error that occurred and is the 

enumeration for the diag_type field, which is of type struct Ft_diagnostic. 


FT_I N FORMATIVE The error does not affect the current file service and therefore, 

does not require recovery. An example is 
F_CREATE_SLCTD_EXIST_FI LE, which means override 
selected an existing file. 

FT_TRANSIENT The current file service is affected. It requires recovery. 

FT_PERMANENT The FTAM request failed. 

Ftentityref 


enum Ft_entity_ref { 

FT_NOT_CATEGORIZED = 0, 
FT_INITIATING_FILE_SERVICE_USER = 1, 
FT_INITIATING_FILE_PROTOCOL_MACHINE = 2, 
FT_SERVICE_SUPPORTING_FILE_PROTOCOL_MACHINE = 3, 
FT_RESPONDING_FILE_PROTOCOL_MACHINE = 4, 
FT_RESPONDING_FILE_SERVICE_USER = 5 


}; 

Ft_entity_ref identifies the entity that detected the error 
(error_observer) and where the error occurred (error_source). You may 
find this information particularly helpful if the error occurs with other 
vendors. 
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Ft_diagnostic 


FT_N OT_CATEGORI ZE D 


FT_I NITI ATI NG_FI LE_SERVI CE_USER 

FT_I NITI ATI NG_FI LE_PROTOCOL_- 
MACHINE 

FT_SERVI CE_-SU PPORTI NG_FI LE_- 
PROTOCOL_MACHIN E 

FT_RESPONDI NG_FI LE_PROTOCOL_- 
MACHINE 

FT_RESPONDI NG_FI LE_SERVICE_- 
USER 


The error may have occurred or been detected 
anywhere. 

The error is in the user program. 

The error is in or detected by the initiator. 

The error is in one of thelower layers, probably 
the Presentation Service. 

The error is in or detected by the responder. 


The error is in or detected by the VFS. 
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FtfaduJ denti ty 

struct Ft_fadu_identity { 

enum Ft_fadu_form fadu_form; 

union Ft_fadu_info fadu_info; 

}; 


Ft fadu i denti ty Is InputTo Ftfaduidentity IsOutput 

These Functions From These Functions 

ft_er ase() ft_l ocate() 

ftj ocate() 

ft_read() 

ft_write() 

Ft_fadu_identity identifies the whole file (the single FADU) for FTAM-1, 
FTAM-3, and INTAP-1 files. This structure also identifies either the 
whole file or individual FADUs for FTAM-2 files. Use the identified 
FAD Us to erase, read, and write (FTAM-1, FTAM-2, and FTAM-3) and to 
locate (FTAM-2 only). 


fadu_form Thefadu_form indicates you will use either a FADU 

location or number. For HP-UX responders, you must use 
locati on. 

fadujnfo Thefadujnfo specifies the FADU location or number. 

Ftfaduform 


enum Ft_fadu_form { 

FT_FADU_LOCATION = 0, 
FT_FADU_NAME = 1, 
F T_F AD U_NAME_L 1ST = 2, 
FT_FADU_NUMBER = 3 


} ; 

Ft_fadu_form isthe type for the fadu_form field in Ft_fadu_identity. 
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• The value specified in fadu_form dictates the value used in fadujnfo. 

• For HP-UX responders, you must specify FT_FADU_LOCATION. 

HP-UX responders return an error if you use FT_FADU_NAME, 
FTNAMEJJST, or FT_N UMBER. 

Ft_fadu_info 

union Ft_fadu_info { 

enum Ft_fadu_location 

Ft_fadu_name 

struct Ft_fadu_name_list 

Sint32 

}; 

Ft_fadu_info isthe type for fadujnfo in struct Ft_fadujdentity and is 
also the union for the enum Ft_fadu_form. 

Ft_fadu_info specifies the actual fadu_identity location. 


fadu_location; 
fadu_name; 
fadu_name_list; 
f adu_numbe r; 


fadujocation Specifies the FADU location you want to access 

within a file. If you selected FT_FADU_LOCATI ON 
in Ft_fadu_form, you must specify fadujocation. 

• The fadujocation is of thetype Ft_fadu_location. 

enum Ft_fadu_location { 

FT_FIRST = 0, 

FT_LAST = 1, 

FT_PREVIOUS = 2, 

FT_CURRENT = 3, 

FT_NEXT = 4, 

FT_BEGIN = 5, 

FT_END = 6 

}; 


FT_FI RST 
FT_LAST* 
FT_PREVI OUS* 

FT CURRENT* 


First FADU in the file. 

Last FADU in the file. 

The FADU immediately before the FADU where 
the file pointer is currently located. 

The FADU wherethefile pointer is currently 
located. 
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FT_NEXT TheFADU immediately after theFADU where 

the file pointer is currently located. 

FT_BEGI N For ft_read(), ft_write(), and ft_erase(), initial 

location in the file, before all FADUs. For 
ft_locate(), earliest FADU in the file. 

FT_END The final location in the file, after all FADUs. 

*ln valid for use with HP-UX responders. 

• Use only FT_FI RST for FTAM-1, FTAM-3, INTAP-1, and NBS-9 
document types (constrained by the Unstructured All constraint set). 

• Use any of the fields for FTAM-2 document type (constrained by the 
Sequential Flat constraint set). 

• You can locate, read, write, and erase the whole file or leaf FADUs as 
defined in the following table. Remember, only FTAM-2 files have leaf 
FADUs. 

• For example, you can locateany of the individual FADUs, but you can 
only erase the whole file. 


ft_locate() ft_read() ft_write() ft_erase() 


Begin 

Leaf FADU 

Whole File 

Whole File 

End 

End of File 


End of File 

First 

Leaf FADU 

Leaf FADU 


Last 

Leaf FADU 

Leaf FADU 


Current 

Leaf FADU 

Leaf FADU 


Next 

Leaf FADU 

Leaf FADU 


Previous 

Leaf FADU 

Leaf FADU 



fadu_name 

fadu_name_list 

fadu_number 

HP-UX responders return an error if you usethese 
fields. 
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F t_fad uoper at i on 

enum Ft_fadu_operation { 

FT_INSERT = 0, 

FT_REPLACE = 1, 

FT_EXTEND = 2 

}; 


Ftfaduoperation Is I nputTo Ftfaduoperation Is Output 

These Functions From These Functions 

ft_write() None 

Ft_fadu_operation specifies the action you are taking on a FADU. 

FT_I NSERT I nserts data at the end of a file (FTAM-2 only). 

FT_REPLACE Replaces the existing FADU contents (FTAM-1, 

FTAM-3, and INTAP-1 only). 

FT_EXTEND Appends data to the end of the existing FADU 
(FTAM-1, FTAM-3, and I NTAP-1 only). 
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Ftfileactions 

typedef Uintl6 Ft_file_actions; 


Ftfileactions Is InputTo Ft file actions IsOutput 

These Functions From These Functions 

ft_create() None 

ft_fopen() 

ft_select() 

If you have access control, Ft_file_actions specifies the allowable actions 
the designated users can perform on a file. If you do not have access 
control, Ft_file_actions specifies the requested actions on the file. 

Ft_file_actions is the type for the actionjist field in struct 
Ft_access_control_elements (defines who can access a file and how they 
can access it). Ft_file_actions is also the type of the requested_access 
parameter in the File Selection regime. 

• Use the FT_FA_XXX defined constants in the mapftam.h header file. 
FT_FA_READ 
FT_FA_I NSERT 
FT_FA_REPLACE 
FT_FA_EXTEND 
FT_FA_ERASE 
FT_FA_READ_ATTRI BUTE 
FT_FA_CHANGE_ATTRI BUTE 
FT FA DELETE FILE 
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Ftfilepasswords 


FT_FA_READ 

FT_FA_I NSERT 
FT_FA_REPLACE 

FT_FA_EXTEND 

FT_FA_ERASE 
FT_FA_READ_ATTRI BUTE 
FT_FA_CH ANGE_ATTRI BUTE 
FT FA DELETE FILE 


Reads contents of the file (FTAM-1, FTAM-3, and 
INTAP-1) or of the FADU (FTAM-2). 

I nserts data at the end of a file (FTAM-2 only). 

Replaces the existing FADU contents (FTAM-1, 
FTAM-3, and INTAP-1 only). 

Appends data to the end of the existing FADU 
(FTAM-1, FTAM-3, and I NTAP-1 only). 

Erases the entire file. 

Reads the file attributes. 

Changes the file attributes.D 

Del etes the enti re fi le. 


F t_fi I e passwords 

struct Ft_file_passwords { 

Ft_single_file_pw read; 

Ft_single_file_pw insert; 
Ft_single_file_pw replace; 
Ft_single_file_pw extend; 
Ft_single_file_pw erase; 

Ft_single_file_pw read_attribute; 
Ft_single_file_pw change_attribute; 
Ft_single_file_pw delete_file; 
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Ftfilepasswords I s Input To 
These Functions 


Ft file passwords Is Output 
From These Functions 


ft_create() None 

ft_fcopy() 

ft_fmove() 

ft_fcattributes() 

ft_fopen() 

ft_frattributes() 

ft_select() 


NOTE Since the H P-UX file system does not define file passwords, HP-UX 

FTAM responders do not use file password information. 


Ft_file_pass w °rds specifies a user password for each action. To use file 
passwords, first negotiate security in Ft_attribute_groups during the 
connection establishment. You must usefile_passwords for each action 
you request if the foil owing conditions are true: 

• The file has an access_control_element with an identity field that 
specifies you. 

• The action listed in actions_list has an associated password. 
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Ftfilestatus 


enum Ft_file_status { 

FT_FS_ENUM_DEFAULT = -1, 

FT_NEW = 0, 

FT_OLD = 1, 

FT_REPLACE_CONTENTS = 2, 

FT_RECREATE = 3, 

FT_UNKNOWN = 4 


} ; 


Ftfilestatus Is InputTo Ft file status IsOutput From 

These Functions These Functions 

ft_create() None 

ft_fopen() 

Ft_file_status determines what action to take in the file specified on 
ft_create() or ft_fopen() already exists. Ft_file_status specifies whether to 
create or select a file and the effects these actions have on the already 
existing file. 

If the file does not exist, a new file is created. 


Ft file status Field 

FT_F S_E N U M_DE FAU LT 

FTJMEW 
FT OLD 


If The File Already Exists 

For ft_create(), request fails 
For ft_fopen(), existing file selected 
Request fails 
E xi sti ng fi I e sel ected 
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FT_REPLACE_CONTENTS Existing file contents deleted 

Existing file attributes remain the 
same 

E xi sti ng fi I e sel ected 


FT RECREATE 


FT UNKNOWN 


Existing file contents and attributes 
deleted 

New file created with attributes 
specified in struct Ft_attributes 

E xi sti ng fi I e sel ected 
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Ft filename 


typedef char 


*Ft_filename; 


Ftfilename s Input To These Ftfilename Is Output From 
Functions These Functions 


ft_create() None 

ft_fcattributes() 

ft_fcopy() 

ft_fdelete() 

ft_fmove() 

ft_fopen() 

ft_frattributes() 

Ft_filename identifies a specific file with a unique path name given in 

the syntax of the original file in the real filestore. 
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Ftfunctionalunits 

typedef Uintl6 Ft_functional_units; 


Ft functional units Input 
To These Functions 

ft_connect() 


Ft functional units Is Output 
F rom These F unctions 

ft_connect() 


Ft_functional_units specifies which functions are available per 
connection. You must use the FT_FU_XXX defined constants to specify 
Ft_functional_units. 

FT_FU_READ 
F T_F U_WR IT E 
FT_FU_FILE_ACCESS 

FT_FU_LTD_MGMT(Limited File Management) 

FT_FU_ENH_MGMT(Enhanced File Management) 

FT_FU_GROUPING 
FT_FU_FADU_LOCKING 
F T_F U_RE C OVE R Y 
FT_FU_RESTART_XFR 

• HP-UX responders accept, but ignore, FT_FU_FADU_LOCKING, 
FT_FU_RECOVERY, and FT_FU_RESTART_XFR. 

• By default, you always have the following functions. 


ft_aeactivation() 

ft_deselect() 

ft_deactivation() 

ft_select() 

ft_ireceive() 

ft_aereset() 

ft_didcb() 

ft_abort() 

ft_dfdcb() 

ft_release() 

ft_gperror() 

ft_connect() 
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• You must negotiate Ft_functional_units on theft_connect() request. 
For example, if you want to be ableto read a file, set FT_FU_READ 
when making theft_connect() request. 

• Ft_service_class dictates the mandatory and optional 
functional_units (as noted in the foil owing table). Ft_service_class 
must support all selected Ft_functional_unit values; otherwise, you 
receive an error. Refer to the "Ft_service_class" section for detailed 
information. 


EXAMPLE: On ft_connect(), if you specify the 

FT_SC_TRANSFER service_class, 

• You must specify FT_FU_GROU PI NG functional_units, 

• You must specify either or both FT_FU_READ and 
FT_FU_WRITE, 

• You may optionally specify either or both FT_FU_LTD_MGMT 
and FT_FU_ENH_MGMT, and 

• You cannot specify FT_FU_FI LE_ACCESS. 

• The kernel functional_unit is always available. 

The foil owing table shows the service_cl asses you should set to use the 
functional_units. Use this key to read the table. 

TSC=FileTransfer Service Class 

ASC=File Access Service Class 

M SC =File Management Service Class 

TMSC=FileTransfer and Management Service Class 

USC=Unconstrained Service Class 

M = Mandatory 

0 ^Optional 

• =Oneor Both 

X =Not Permitted 
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Ft functional units 


See the previous page for the reference key to this table. 


Functional 

FTAM 

Unit 

Functions 

Kernel 

ft_abort 

ft_aeactivation 

ft_aedeactivation 

ft_aereset 

ft_connect 

ft_deselect 

ft_i receive 

ft_rrequest 

ft_select 

Read 

ft_cancel 

ft_close 

ft_etransfer 

ft_open 

ft_rcancel 

ft_rdata 

ft rdataqos 

ft_read 

Write 

ft_cancel 

ft_close 

ft_edata 

ft_etransfer 

ft_nwcl eared 

ft_rcancel 

ft_sdata 

ft_open 

ft_sdata 

ft_write 

File Access 

ft_erase 

ft_locate 

Limited File 

ft_create 

M anagement 

ft_delete 

ft_rattributes 

Enhanced File 

M anagement 

ft_cattributes 

Grouping 

ft_bgroup 

ft_egroup 


TSC ASC MSC TMSC USC 

M M M M M 


MX* 0 


MX* 0 


X M X X 0 

0 0 M M 0 

OOOO 0 

M 0 M M 0 
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Ftjnitiatorjdentity 

typedef char *Ft_initiator_identity; 


F ti n i ti atori denti ty I s I n put 
To These Functions 

ft_connect() 
ft_fdelete() 
ft_fcattributes() 
ft_fcopy() 
ft_fmove() 
ft_frattributes() 

Ftjnitiatorjdentity identifies the HP-UX login account if using H P-UX 
responders. This structure is the type for the foil owing fields and 
specifies the foil owing user identities. 


Ftjnitiatorjdentity Is 
Output From These Functions 

None 


i dent i ty_of_creator 
identity_of_modifier* 
identity_of_reader* 
i dentity_of_attri bute_mod* 
initiatorjdentity* 


User who created the file 

User who last modified the file 

User who last read the file 

User who last modified file attributes 

User's login account 

In Ft_access_control_element, user 
who has the access privileges 


* HP-UX responders accept, but ignore, these values. 
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Ft processi ng mode 

typedef Uintl6 Ft_processing_mode; 


Ftprocessing mode Input Ft processing mode Is Output 

To These Functions From These Functions 

ft_open() None 

Ft_processing_mode specifies the cur rent file action for ft_open () (i.e., 
specifies an action you want to perform now). 

• These actions must be a subset of those actions selected in 
requested_access (FT_FA_XXX defined constants). 

• Only after closing the file can you specify other actions through 
Ft_processing_mode (if you first re-open the file). 

• You must use one of the foil owing FT_PM_XXX defined constants to 
specify Ft_processing_mode: 


FT_PM_READ Reads contents of thefile (FTAM-1, FTAM-3, 

INTAP-1, and NBS-9) or of the FADU 
(FTAM-2). 

FT_PM_I NSERT I nserts data at the end of a file (FTAM-2 only). 

FT_PM_REPLACE Replaces the existing FADU contents (FTAM-1, 
FTAM -3, and I NTAP-1 only). 

FT_PM_EXTEND Appends data to the end of the existing FADU 
(FTAM-1, FTAM-3, and I NTAP-1 only). 

FT_PM_ERASE Erases the entire file. (FTAM-1, FTAM-2, 
FTAM-3, and I NTAP-1 only). 
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Ftqos 

enum Ft_qos { 

FT_NO_RECOVERY = 0, 

F T_C LAS S_1_RE COVE RY = 1, 
FT_CLASS_2 _RE C 0 VE R Y = 2, 
F T_CLAS S_3_RE COVE RY = 3 

}; 


Ftqos Is Input To These Ftqos Is Output From These 
Functions Functions 

ft_connect() ft_connect() 


Ft_qos determines the level of recovery by FTAM by specifying which 
recovery classes are active. The qos stands for quality of service. 


FT_NO_RECOVERY 

FT_CLASS_l_RECOVERY 

FT_CLASS_2_RECOVERY 

FT_CLASS_3_RECOVERY 


FTAM does not automatically attempt recovery. You must 
select FT_NO_RECOVERY and perform the recovery. 

Transient errors occurring during data transfer are 
recovered by restarting the data transfer. 

Transient errors occurring during data transfer are 
recovered by restarting the select/open regime. 

Not supported. If this class is selected, you will receive the 
error FTE 173_INV_FTQOS. 


Chapter 3 


149 



HP FTAM/9000 Data Structures 

Ft_service_class 


F t ser vi ce_c I ass 

typedef Uintl6 Ft_service_class; 


Ftserviceclass Is Input To Ftserviceclass Is Output 
These Functions From These Functions 

ft_connect() ft_connect() 

Ft_service_class specifies whether you transfer, access, or manage a file 
per connection. You must use one of the foil owing FT_SC_XXX defined 
constants to specify Ft_service_class: 


Service Class 

Unconstrained 

FT_SC_U N CON STRAI NED 

File Management 
FT_SC_MANAGEMENT 


Description 

Allows you to request any 
combination of functional_units 
with the mandatory kernel group 

Allows you to manipulate whole 
files 

Change attributes 
Create files 
Delete files 
Read attributes 
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Ft service class 


File Transfer 
FT_SC_TRAN SF E R 
File Transfer and Management 
FT_SC_TRAN SF E R_AN D_M GMT 


File Access 
FT_SC_ACCESS 

You can use any of the following combinations of service_cl asses. Note, 
you cannot use FT_SC_UNCONSTRAI NED by itself; you must use it in 
conjunction with other service_classes. 

* FT_SC_M AN AGE M E NT 

* FT_SC_TRANSFER 

* FT_SC_ACCESS 

* FT_SC_TRANSFER and FT_SC_ACCESS 

* FT_SC_MANAGEMENT, FT_SC_TRANSFER, and 
FT_SC_TRAN SF E R_AN D_M GMT 

* FT_SC_MANAGEMENT, FT_SC_TRANSFER, FT_SC_ACCESS, 
and FT_SC_TRANSF ER_AN D_MGT 

* FT_SC_U NCONSTRAI NED and FT_SC_MANAGEMENT 

* FT_SC_U N CON STRAI N E D and FT_SC_TRAN SF E R 

* FT_SC_U N CON STRAI NED and FT_SC_ACCESS 


Allows you to transfer data 

Allows you to move or copy bulk 
data 

Allows you to manipulate whole 
files: 

Change attributes 
Create files 
Delete files 
Read attributes 

Combines all capabilities of File 
Transfer and File Management 

Allows you to transfer data 

Provides you with access to 
individual FADUs 
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Ft_service_class 


• FT_SC_UNCONSTRAI NED, FT_SC_TRANSFER and 
FT_SC_ACCESS 

• FT_SC_UN CON STRAI NED, FT_SC_MANAGEMENT, 
FT_SC_TRANSFER, and FT_SC_TRANSFER_AND_MGMT 

• FT_SC_UN CON STRAI NED, FT_SC_MANAGEMENT, 
FT_SC_TRANSFER, FT_SC_ACCESS, and 
FT_SC_TRAN SF E R_AN D_M GT 

• You must negotiate Ft_service_class when calling ft_connect(). 

• Ft_service_class defines the mandatory and optional 
Ft_functional_units. Set these restrictions using the defined 
constants. Each FT_SC_XXX dictates which FT_FU_XXX 
(Ft_functional_unit) defined constants are mandatory and optional 
(as noted in the following table). 


On ft_connect(), if you specify the FT_SC_TRAN SF E R_AN D_M GT 
service_class, 

• You must specify FT_FU_GROUPING and FT_FU_LTD_MGMT 
functional_units, 

• You must specify either or both FT_FU_READ and FT_FU_WRITE, 

• You can optionally specify FT_FU_ENH_MGMT, and 

• You cannot specify FT_FU_FILE ACCESS. 
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Ft_service_class 


Service Class 

Mandatory 

Functional 

Units 

One or Both 
Functional 
Units 

Optional 

Functional 

Units 

Not Allowed 

Unconstrained 

• Kernel 


• Enhanced 
File Mgmt 

• File Access 

• Group 

• LimitedFile 
Mgmt 

• Read 

• Write 


Management 

• Kernel 

• Grouping 

• Limited File 

M anagement 


• Enhanced 
File Mgmt 

• File Access 

• Read 

• Write 

T ransfer 

• Kernel 

• Grouping 

• Read 

• Write 

• Enhanced 
File Mgmt 

• LimitedFile 
Mgmt 

• File Access 

Transfer and 
Management 

• Kernel 

• Grouping 

• Limited File 
Mgmt 

• Read 

• Write 

• Enhanced 
File Mgmt 

• File Access 

Access 

• Kernel 

• File Access 

• Read 

• Write 


• Enhanced 
File Mgmt 

• Grouping 

• LimitedFile 
Mgmt 



Ft_service_class restricts the way in which you can group functions (with 
ft_egroup()). Refer to the foil owing table and list to determine these 
restrictions. 

• If using FT_SC_TRANSFER, open the file with group #1, transfer 
data as needed, and close the file with group #, 2. 

• If using FT_SC_M ANAGEM ENT, you must use group #3 and you 
cannot call low level functions outside of this group. 
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• If using FT_SC_TRANSFER_AND_MGMT, you must use group #1 
and #, 2, or use group #3, as follows. 

• Open the file with group #1, transfer data as needed, and close the 
file with group A2 OR 

• Use group #3 to select or create a file, read or change attributes, 
and deselect or delete the file. 

• If you select FT_SC_ACCESS, you can use any of the groupings. 


Mandatory 

Beginning 

Functions 

Must Have 
One of these 
Functions 

Optional 

Functions 

Must Have 
One of these 
Functions 

Mandatory 

Ending 

Functions 

#1 ft_bgroup() 

ft_select() 

ft_create() 

ft_rattributes() 

ft_cattributes() 

ft_open() 

ft_egroup() 

AS ft_bgroup() 

ft_close() 

ft_rattributes() 

ft_cattributes() 

ft_deselect() 

ft_delete() 

ft_egroup() 

A3 ft_bgroup() 

ft_select() 

ft_create() 

ft_rattributes() 

ft_cattributes() 

ft_deselect() 

ft_delete() 

ft_egroup() 

M ft_bgroup() 

ft_select() 

ft_create() 

ft_rattributes() 

ft_cattributes() 


ft_egroup() 

AS ft_bgroup() 


ft_rattributes() 

ft_cattributes() 

ft_deselect() 

ft_delete() 

ft_egroup() 
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F t_si n gl e_fi I e pw 

typedef struct Octet_string Ft_single_file_pw; 


Ftsinglefilepw s Input To 
These Functions 

ft_connect() 
ft_create() 
ft_fcattributes() 
ft_fcopy() 
ft_fdelete() 
ft_fmove() 
ft_frattributes() 

Ft_single_file_pw is of type struct Octet_string which contains a length 
field (Uintl6) and a pointer field (Octet_pointer). The meaning of 
Ft_single_file_pw varies as noted in the following table. 


Ft single file pw Is Output 
From These Functions 

None 


Function 

F t_si n gl e_fi 1 e pw 

ft connectO 
ft_fcattributes() 
ft fdeleteO 
ft_frattributes() 

file_store_pw 

ft_create() 

fcopyO 

ft_fmove() 

create_file_pw 

ft_fcopy() 

source_filestore_p 

ft_fmove() 

wdest_fi 1 estore_pw 

ft_fdelete() 

delete_file_pw 


Description 

Password for initiatorjdentity. 


Password to establish 
permission to create files in the 
filestore; HP-UX responders 
accept, but ignore, this value. 

Password for sourcejnitjd. 
Password for destjnitjd. 
Password to establish 
permission todeletefiles in the 
filestore. HP-UX responders 
accept, but ignore, this value. 
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inoutdcb 

You receive large amounts of data from the FTAM interface. To reduce 
the number of exposed parameters, Ft_output and Ft_xxx_out_dcb 
contain agroupof parameters. Thexxx varies, depending on thefunction 
(e.g., Ft_rdata_out_dcb). Except for size, all inout_dcb parameters are 
output parameters. 

Ftoutput 

struct Ft_output { 

Uint32 size; 

struct Api_rc result; 

}; 


Ftoutput Is Input To These 
Functions 

Only the Ft_output size 
parameter and only if you use 
Ft_output in those cal Is listed in 
the output column 


Ft output Is Output From 
These Functions 

ft_abort() 

ft_aeactivation() 

ft_aedeactivation() 

ft_aereset() 


You must either pass the address of an Ft_output or you must pass the 
address of a N U L L val ue. I f you pass the address of an F t_output, you 
must have enough memory to return size and result. 


size The size of the Ft_output structure and associated data 
in Octets. The size parameter is mandatory input if 
using Ft_output. 

result The result is of type Api_rc and provides error 
information. 
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F txxxoutdcb 


struct Ft_xxx_out_dcb { 

Uint32 size; 

struct Api_rc result; 

Function-specific info; 


Ftxxxoutdcb Is Input To 
These Functions 

Only the Ft_xxx_out_dcb size 
parameter and only if you use 
F t_xxx_out_dcb i n those cal I s 
I i sted i n the output col u mn 


Ft xxx out dcb Is Output 
From These Functions 

ft bgroupO 

ft_cancel() 

ft_cattributes() 

ft_close() 

ft_connect() 

ft_create() 

ft_delete() 

ft_deselect() 

ft_edata() 

ft_egroup() 

ft_erase() 

ft_etransfer() 

ft_fcattributes() 

ft_fclose() 

ft_fcopy() 

ft_fdelete() 

ft_frattributes() 

ft_fmove() 

ft_fopen() 

ft_ireceive() 

ft_locate() 

ft_nwcleared() 

ft_open() 

ft_rattributes() 

ft_rcancel() 

ft_rdata() 

ft_read() 

ft_rrequest() 

ft_sdata() 

ft_select() 

ft_write() 
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You must either pass the address of an inout_dcb or you must pass the 
address of a a N U L L val ue. I f you pass the address of an i nout_dcb, you 
must have enough memory to return size and result. You may or may not 
supply additional values, depending on the function. 


size The size of the Ft_xxx_out_dcb structure and associated data 
in Octets. The size parameter is mandatory input if using 
F t_xxx_out_dcb. 

result The result is of type Api_rc and provides error information. 


Memory Allocation for inoutdcbs 

For asynchronous calls, the memory occupied by Ft_output and 
Ft_xxx_out_dcb is logically inconsistent until the request completes. 
Therefore, you should not reference the inout_dcb from the time the 
asynchronous call returns SUCCESS until em_wait() verifies completion 
of the request. 

You can allocate memory for Ft_output and Ft_xxx_out_dcb in three 
ways. 

• The recommended method is to have the output inout_dcb parameter 
reference the address of a NULL value when making the call. By 
doing so, the FTAM interface allocates the memory necessary; thus, 
you avoid having to anticipate how much memory is required. 

After the FTAM function returns or for asynchronous calls, after 
em_wait() returns SUCCESS, you must call ft_dfdcb() to free the 
memory (even though the FTAM interface allocated the memory). 

• Al locate the memory yourself (e.g., using mallocO or using variables). 
Ensure the size field is large enough to hold all possible return 
information; otherwise, you may receive an 

FTE004_OUTPUT_BUFFER_0VERFL0W error. For example, you 
want to have a size large enough to store the i nout_dcb structure and 
all possible returning diagnostics (a linked list of 14). 

• Before the request, invoke ft_didcb() to allocate memory for 
Ft_xxx_out_dcb. Free the memory used by the input_dcb parameter 
by invoking ft_dfdcb() after the function returns (synchronous calls) 
or after em_wait() returns (asynchronous calls). Ensure the 
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additional_size parameter is large enough to hold all possible return 
information (e.g., diagnostics and returned data); otherwise, you 
receive an FTE004_OUTPUT_BUFFER_OVERFLOW error. 


NOTE Your application must not perform any operations on or with an inout 

DCB parameter until em_-wait() indicates the cal I iscomplete. Failureto 
follow this rule can cause serious internal errors to occur, resulting in 
unpredictable behavior or software failures. 
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input deb 

struct Ft_xxx_in_dcb 
{ 


}; 


Ftxxxindcb Is Input To 
These Functions 

ft_abort() 

ft_aeactivation() 

ft bgroupO 

ft_cancel() 

ft_cattributes() 

ft_close() 

ft_connect() 

ft_create() 

ft_delete() 

ft_deselect() 

ft_edata() 

ft_egroup() 

ft_erase() 

ft_etransfer() 

ft_fcattributes() 

ft_fclose() 

ft_fcopy() 

ft_fdelete() 

ft_frattributes() 

ft_fmove() 

ft_fopen() 

ft_ireceive() 

ft_locate() 

ft_open() 

ft_rattributes() 

ft_rcancel() 

ft_read() 

ft_rrequest() 

ft_select() 

ft_write() 


Ft xxx in dcb Is Output 
From These Functions 

None 
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You pass large amounts of data to the FTAM interface. To reduce the 
number of exposed parameters, the Ft_xxx_in_dcb contains optional and 
function-specific parameters. 

The input_dcb parameters may be mandatory or optional; they must 
occur after the exposed input parameters and before the inout_dcb 
parameters. I f any of the i nput_dcb parameters are mandatory, you must 
pass the address of an input_dcb; otherwise, you may pass a N U LL 
value. 

You can al locate memory for F t_xxx_i n_dcb two ways. I f you are usi ng 
optional parameters, remember to allocate memory for them. 

• Al locate the memory yourself (e.g., using mallocO and free(), or C 
variables). 

• Before the request, a recommended practice is to invoke ft_didcb() to 
allocate memory for Ft_xxx_in_dcb and then set the appropriate 
Ft_xxx_in_dcbfields. After the request completes, invokeft_dfdcb() to 
free the memory used by Ft_xxx_in_dcb. 
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Local event name 

typedef Sint32 Local_event_name; 


L ocaleventna me I s I n put To 
These Functions 

ft_abort() 

ft_aeactivation() 

ft_aedeactivation() 

ft_aereset() 

ft bgroupO 

ft_cancel() 

ft_cattributes() 

ft_close() 

ft_connect() 

ft_create() 

ft_delete() 

ft_deselect() 

ft_edata() 

ft_egroup() 

ft_erase() 

ft_etransfer() 

ft_fcattributes() 

ft_fclose() 

ft_fcopy() 

ft_fdelete() 

ft_frattributes() 

ft_fmove() 

ft_fopen() 

ft_ireceive() 

ft_locate() 

ft_nwcleared() 

ft_open() 

ft_rattributes() 

ft_rcancel() 

ft_rdata() 

ft_read() 

ft_rrequest() 

ft_sdata() 

ft_select() 

ft_write() 


Localeventname Is Output 
From These Functions 

em_wait() 
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Local_event_name uniquely identifies a specific asynchronous function 
call and also determines whether a call is synchronous or asynchronous. 

If the cal I is synchronous, the value must be zero (0). 

Theem_wait() function uses Local_event_nameto identify a completed 
asynchronous operation. This identification is the same value that you 
passed to the operation when you initiated it. Though em_wait() can wait 
on multiple asynchronous operations, only one Local_event_name 
returns per call. You must know the Local_event_name of the event for 
which you are waiting. 

Each outstanding asynchronous function must have a unique 
Local_event_name with a value greater than zero (0). A recommended 
practice is to start with the value one (1) and then increase by 
increments. You will find this method especially helpful when tracking 
i ncomi ng events. 
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P address 


struct P_address 
{ 

struct Octet_string *p_selector; /* NULL if it is not present */ 

struct Octet_string *s_selector; /* NULL if it is not present */ 

struct Octet_string *t_selector; /* NULL if it is not present */ 

Sint16 n_nsaps; /* Number of NSAPs */ 

struct Octet_string *nsaps; /* ptr to a sequence of NSAPs */} ; 
/* Maximum length of psap_selector is 16 Octets. 

* Maximum length of ssap_selector is 16 Octets. 

* Maximum length of tsap_selector is 32 Octets. 

* Maximum length of NSAP is 20 Octets. 

* Maximum number of NSAPS is 8. 

*/ 


Paddress I s I nput To These Paddress I s Output From 
Functions These Functions 

ft_connect() ft_connect() 

As an alternative to specifying the directory distinguished name, you can 
specify the P_address when i nvoki ng ft_connect() to communicate with 
other systems and processes. 

TheP_address must be unique within the network and must be exactly 
the same as the one set during configuration. To have the system 
automatically set the P_address structure, call convert_paddr; the source 
is in /opt/ftam/demos/cnvrt_addr.c. 

• Each application on a node must have a unique triple of p_selector, 
s_selector, and t_selector. For example, one application could have 
(0000,0000,0000), another (0000,0000,0001), and another 
(2375,232323,75757575). 

• Each node must have a unique nsap. 

• The maximum length of the P_address is 224 Octets. These Octets 
can be printable or unprintable characters. 

• Each called_dir_name has a corresponding P_address. Directory 
Services provides the mapping between the two. 
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p_selector 


s selector 


t selector 


n_nsaps 


nsaps 


Presentation ServiceAccess Point Selector: unique value 
that allows network layers to identify the connection to 
its peer. 

Session ServiceAccess Point Selector: unique value that 
allows network layers to identify the connection to its 
peer. 

Transport ServiceAccess Point Selector: unique value 
that allows network layers to identify the connection to 
its peer. 

Number of nsaps (Network ServiceAccess Points) 


The maximum number of nsaps is eight. 


You might want to have multiple nsaps to uniquely label 
cards if using two network cards on one machine. 

Network ServiceAccess Point: uniquevaluethat allows 
network layers to identify the connection to its peer. 
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Use support functions for a variety of purposes, such as managing your 
memory. Refer to the "Example Programs" chapter for model programs 
using the support functions. 
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NOTE References to Event M anagement functions mean the combination of 

em_fdmemory(), em_wait(), and em_gperror(). 


Support functions are not bound to a specific regime. The only exception 
is ft_nwcleared(), which is used only when ft_sdata() returns the error 
FTE008_NO_CON_RESOU RCES. 
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C hapter Overview 

Thischapter describes the following functions in the order listed. 


Task to Perform 

Function Used 
to Perform the 
Task 

Description 

Managing Memory 

ft_dfdcb() 

De-allocate memory for DCBs (dynamic DCB 
de- allocation) 


ft_didcb() 

Allocate memory for DCBs (dynamic DCB 
allocation) 


em_fdmemory() 

F ree dynami c memory al 1 ocated by 
em_gperror() for the return_code and 
vendor_code stri ngs 


ft_fdmemory() 

F ree dynamic memory allocated by ft_gperror() 
for the return_code and vendor_codestrings 

Responding to 
Asynchronous Calls 

em_wait() 

Suspends application processing until a MAP 
event occurs 


em_hp_select() 

Suspends application processing until a MAP 
or non- MAP event occurs 


em_hp_sigio() 

Notifies that an asynchronous call completed 
by way of a SIGIO 

Translating Error 

M essages 

em_gperror() 

Translate returned Event Management 
return_codes and vendor_codes to printable 
strings 


ft_gperror() 

Translate returned FTAM return_codes and 
vendor_codes to printable strings 

Determining 
Available Resources 

ft_nwcleared() 

Determine that a resource constraint cleared 
and that resource is now available 
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Managing Memory 

Useft_didcb() and ft_dfdcb() to manage your DCB memory by allocating 
and de-allocating memory for DCB structures. Refer to the "Using 
FTAM " chapter for recommendations on allocating memory. 

ftdidcbO 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_didcb (dcb_type, additional_size, dcb_pointer, result) 
enum Ft_dcb_type dcb_type; 

Uint32 additional_size; 

Octet **dcb_pointer; 

Api_rc *result; 


Useft_didcb() to allocate memory for Ft_xxx_in_dcb or Ft_xxx_out_dcb 
structures. This function allocates the desired memory at the location 
poi nted to by dcb_poi nter. 

• When allocating memory for an inout_dcb, you may optionally use the 
additional_size field to allocate more memory than the size of the 
DCB structure. All fields that are pointers may need additional 
memory. You must provide a large enough additional_size to contain 
all returning output. 

• The outcome of ft_didcb() does not return in result if you pass an 
invalid result structure address on input. 
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ft_didcb() Parameters 


ftdidcbO 

Parameter 

dcb_type 
additional_size 
dcb_poi nter 

result 


Type 

Mandatory 
I nput 

Optional I nput 
inout_dcb only 

I nput 

Output 

Output 


Description 

Identifies the DCB to initialize 


Specifies the amount of memory al I ocated beyond that 
allocated for the DCB 

Address of the DCB to initialize 

Address of the DCB pointer 

Pointer to the struct Api_rc containing the outcome of 
the operation: result_code (MAP 3.0 error) and 
vendor_code (HP-UX—specific error) 


ftdfdcbO 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_dfdcb (dcb_pointer, result) 

Octet *dcb_pointer; 

Api_rc *result; 

Useft_dfdcb() tode-allocate memory that was allocated by ft_didcb(). 
Also useft_dfdcb() to de-allocate memory if you specified NULL for the 
inout_dcb when calling an FTAM function. 

• If you allocated memory (e.g., using mallocO), you cannot call 
ft_dfdcb() to de- allocate memory. 

• The outcome of ft_dfdcb() does not return in result if you pass an 
invalid result structure address on input. 
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dcb_poi nter 
result 
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Managing Memory 

ft_dfdcb() Parameters 


Type 


Description 


M andatory Address of the DCB to free 
I nput 

Output Pointer to the struct Api_rc containing the outcome of 

the operation: result_code (MAP 3.0 error) and 
vendor_code (H P-UX—specific error) 


emfd memor y () 

#include %</opt/ftam/include/map.h> 
Return_code 

em_fdmemory(memory_pointer, result) 
Octet *memory_pointer; 

Api_rc ^result; 


Use em_fdmemory() to free dynamic memory al located by em_gperror() 
for the return_code and vendor_codestrings. Note, if you supplied the 
memory for em_gperror(), do not use em_fdmemory() to free it. 

• You may receive unpredictable results if using free() for memory 
allocated by em_gperror(). 

• The outcome of em_fdmemory() does not return in result if you pass 
an invalid result structure address on input. 

• If you allocated memory yourself (e.g., using malloc()), you must also 
free the memory. 
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em fdmemoryO Parameters 


emfd memory () 
Parameter 


Type 


Description 


memory_poi nter 


Mandatory Points to the beginning of the string; address of the 
I nput dynamic memory to free (allocated by em_gperror()) 


result Output Pointer to the struct Api_rc containing the outcome 

of the operation: result_code (M AP 3.0error)and 
vendor_code (H P-UX—specific error) 


ftfd memory () 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
Return_code 

ft_fdmemory (memory_pointer, result) 
Octet *memory_pointer; 

Api_rc ^result; 


Useft_fdmemory() to free dynamic memory allocated for ft_gperror() 
return_code and vendor_code strings. Note, if you supplied the memory 
for ft_gperror(), do not useft_fdmemory() to free it. 

• You may receive unpredictable results if using free() for memory 
allocated by the FTAM library. 

• The outcome of ft_fdmemory() does not return i n result if you pass an 
invalid result structure address on input. 

• If you allocated memory yourself (e.g., using malloc()), you must also 
free the memory. 
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ftfdmemoryO Parameters 


ftfdmemoryO 

Parameter 


Type 


Description 


memory_pointer Mandatory Points to the beginning of the string; address of the 

I nput dynamic memory to free (allocated by ft_gperror()) 

result Output Pointer tothestruct Api_rc containing the outcome of 

the operation: result_code (MAP 3.0 error) and 
vendor_code (H P-UX—specific error) 
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Responding to Asynchronous Calls 

The MAP 3.0 Event Management interface plays a central role in your 
use of asynchronous calls to FTAM functions. 

It is common to have multiple asynchronous function calls outstanding. 
As responses to these calls come in, the FTAM Service Provider Process 
(SPP) queues them. The Event Management interface takes the first 
response off this queue and returns it to the caller as a MAP 3.0 event. 
At the same time, the Event Management interface updates the called 
function's inout DCB to show the outcome of the asynchronous call. 

The FTAM/9000 implementation of MAP 3.0 Event Management 
consists of three functions, each used under slightly different 
circumstances. The functions are: 

• em_wait() 

• em_hp_select() 

• em_hp_sigio() 

Whenever possible, use only em_wait() to wait for and obtain MAP 
events. Sinceem_wait() is the only one of the three defined by the MAP 
3.0 specification, using it eases porting to non-FI P platforms. However, 
em_wait() is also very limited. Sometimes, you may have no alternative 
but to use one or both proprietary functions instead of or in addition to 
em_wait(). 

Following are some guidelines for each of the three event management 
functions. 

When to Use em_wait() 

The em_wait() function enables you to suspend application processing 
until a MAP event occurs. However, em_wait() does not provide for 
waiting on any non-MAP events. 

Use em_wait() when your application needs to wait exclusively on MAP 
3.0 events. For example, if your application is a daemon process which 
interacts only with the OSI network via FTAM protocols. 
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When to Use em hp selectQ 

Theem_hp_select() function is a Hewlett-Packard proprietary extension 
to the MAP 3.0 specification. It can be regarded as a hybrid of the MAP 
3.0 em_wait() function andtheHP-UX selectO system call. It is located in 
the common MAP library (Iibmap.a). 

Useem_hp_select() instead of em_wait() when your application needs to 
wait on MAP events, plus non-MAP events that can be represented by a 
file descriptor and waited on via the HP-UX selectO system call. This 
may be true if your application is interactive (for example, using 
asynchronous input from Terminal I/O or theXll Window system). It 
also may be true if your application needs to communicate with other 
processes via named pipes or domain sockets as well as perform FTAM 
operations over the OSI network. 

In addition, use em_hp_select() instead of em_wait() if your application 
would otherwise need em_wait() to return when interrupted by a signal. 
Theem_hp_select() function does not return by itself when interrupted 
by a signal, but techniques exist tosimulatethis behavior. Seethe 
section on handling signal interrupts with em_hp_select(). 

When to Use em_hp_sigio() 

Theem_hp_sigio() function is another Hewlett-Packard proprietary 
extension in the common MAP library (libmap.a). It enables the Event 
Management interface to notify your application viatheSIGIO signal 
whenthereisa MAP 3.0event pending. However, em_hp_sigio() does not 
return any MAP events itself. Therefore, it should complement your use 
of em_wait() or em_hp_select(). 

Use em_hp_sigio() along with em_wait() or em_hp_select() when your 
application needs to control the dispatch of MAP and non-MAP 
components by using signals and/or semaphores to indicate when a 
particular component has work to do. This is often necessary when 
porting applications from other operating systems such as AT& T's 
System V Unix or DEC'S VMS. 
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Using em_wait() 

#include %</opt/ftam/include/map.h> 
Return_code 

em_wait (timeout, return_event_name, result) 
Em_t timeout; 

Local_event_name *return_event_name; 

Api_rc ^result; 


This section describes general use of asynchronous calls with em_wait(). 
For additional details on em_wait(), refer to the FI P FTAM/ 9000 
Reference Manual. 

Call functions asynchronously when making multi pie requests and when 
the order in which results are processed does not matter. If you make an 
asynchronous call, you can perform other operations while your request 
is being processed. Following are examples of when tocall functions 
asynchronously or synchronously. 

• If you cannot call function B before function A completes, you should 
call function A synchronously. 

• If copying a filetofour different nodes and the processing order does 
not matter, you would call ft_copy)) asynchronously and then wait on 
the return_event_names to know when each ft_copy() completed 
successfully. 
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The following text describes the sequence of making asynchronous 
requests and checking for their successful return from the responder. 

1. Submit one or more asynchronous requests, each with a unique 
r et u r n_event_n a me. 

2. Call em_wait() to determine if the requests returned successfully 
from the responder; you cannot specify the return_event_name for 
which you want to wait. 

Though em_wait() function waits on multiple asynchronous calls, it 
returns return_event_names one at a time and in the order that each 
call completes. 

3. Check the inout_dcb of the FTAM function (specified by the 
return_event_name) to determine the result of a completed request. 
Note, the inout_dcb pointer and structure are not valid until the 
em_wait() request returns successfully. 

Since events can return in any order, the return_event_name 
returned may or may not be the first operation you requested or the 
one on which you are waiting. 

A return_event_name returns only once. Therefore, you should 
process the inout_dcb for all return_event_names in the order in 
which they return or track all the return_event_names that return 
(for future use). 

4. Continue cal ling em_wait() until you receive the return_event_name 
you want. If applicable, call em_wait() until all requests are 
processed. 


NOTE Do not perform any operations on or with an inout_dcb pointer or 

structure until em_wait() indicates the call using the inout_dcb is 
complete. 
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Following is an example of the use of em_wait(). This example creates 
and opens a file by asynchronously calling ft_bgroup(), ft_create(), and 
ft_open(), followed by synchronously calling ft_egroup(). These functions 
were called with return_event_names of 1, 2, 3, and 0, respectively. The 
em_wait() function waits on these calls. 


struct Ft_bgroup_out_dcb 
struct Ft_create_out_dcb 
struct Ft_open_out_dcb 
Em_t 

L o c al_eve nt_name 

Api_rc 

int 

Return_code 

struct Ft_diagnostic 


*bgr_inout_dcb; 

*cre_inout_dcb; 

*ope_inout_dcb; 

time; 

return_event_name; 
result; 
i; 

res; 

*diag = NULL; 


/* This loop waits on the three previously submitted 
asynchronous calls. */ 

for (i = 1; i %<= 3; ++i) { 

time = -1; 

/* Call em_wait() to receive the latest event. */ 
res = em_wait(time, & return_event_name, & result); 
if (res != SUCCESS) 

error_handler(result, diag); 

/* Check the result of each function. */ 
switch (return_event_name) { 
case 1: 

if (bgr_inout_dcb->result.return_code != SUCCESS) 
error_handler(bgr_inout_dcb->result, diag); 
break; 
case 2: 

if (cre_inout_dcb->result.return_code != SUCCESS) 
error_handler(cre_inout_dcb->result, 

cre_inout_dcb->diagnostic); 

break; 
case 3: 

if (ope_inout_dcb->result.return_code != SUCCESS) 
error_handler(ope_inout_dcb->result, 

ope_inout_dcb->diagnostic); 

break; 
default: 
break; 
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Using emhpselectQ 


#include %</opt/ftam/include/map.h> 

Return_code 

em_hp_select (timeout, return_event_name, nfds, readfds, 
writefds, exceptfds, result) 

Em_t timeout; 

Local_event_name *return_event_name 

int *nfds 

unsigned *readfds 

unsigned *writefds 

unsigned *exceptfds 

Api_rc *result; 


This section describes how to use em_hp_select() and provides two 
program examples. For additional details, refer to the HP FTAM/9000 
Reference Manual. 


NOTE FTAM events are asynchronous FTAM operations that complete. 

Non-FTAM events consist of any type of descri ptor supported by the 
select(2) system call that becomes readableor writable, or has exceptions 
pending. 


Multiple asynchronous FTAM functions calls are commonly outstanding 
at the same time. An application may also need to interact with other 
processes using an interprocess communication mechanism (for instance, 
HP-UX Domain Sockets or pipes). It may also require response to 
asynchronous events from a terminal keyboard or window system (for 
instance, X- Windows). 

The MAP 3.0 Event Management interface does not provide an 
independent method to wait on both FTAM and non-FTAM events 
simultaneously. Therefore, HP added a proprietary 
function—em_hp_select()—to provide this capability. 

Neither em_wait() nor em_hp_select() automatically return when 
interrupted by a signal. However, the foil owing section describes a way to 
make a signal generate a non-FTAM event, causing em_hp_select() to 
return on receipt of a signal. 
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Waiting On FTAM and Non-FTAM Events 

Use the em_hp_select() function when an application must 
simultaneously wait for both an FTAM and a non-FTAM event to occur. 

Without em_hp_select(), the application would need to implement a 
"busy- wait" loop to poll for the FTAM and non-FTAM events. Flowever, 
this technique is very expensive in terms of CPU utilization, and 
degrades system performance. This is unacceptable for most real-time or 
highly interactive applications. Therefore, hi P provides em_hp_select() as 
an alternative method for waiting on both FTAM and non-FTAM events. 

Theem_hp_select() function suspends processing of the application until 
an event occurs. Whilethe application is suspended (i.e, blocked), it does 
not contribute to the demand for CPU time. Therefore, the busy-wait 
logic can be replaced with the following: 

em_hp_select(...with indefinite timeout to block until event 
occurs...) 

handle_event) ) 

If you need to wait only on FTAM events, use the em_wait() function. If 
you need to wait only on non-FTAM events, use the FiP-UX selectO 
system call. FI owever, if you need to wait on both types of events 
simultaneously, usetheem_hp_select() function. Any combination of 
em_wait(), selectO, and em_hp_select() within the same program is valid; 
all three functions are compatible with one another. 

The following program example illustrates how to use em_hp_select() to 
wait on FTAM and non-FTAM events simultaneously. The program 
reads commands from stdin and starts the requested FTAM operation. 
The operation is performed asynchronously so that new commands can 
be read in beforethe previous operation completes. The operation results 
are processed as they complete. 

This program cal Is two functions to process the FTAM and non-FTAM 
events. The logic for these functions is not shown in the example; 
however, a brief description of each function follows. 

read_and_process_command(). This function processes the 
non-FTAM events by reading and parsing a command line string from 
stdin. If the command is a "Quit" command, the function returnsTRUE 
to indicate termination. Otherwise, the appropriate FTAM operation is 
initiated asynchronously. I n this case, the function returns FALSE to 
indicate more commands can be read from stdin. 
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For example, this function could be a batch entry console for file 
management. Several file transfers could be started without having to 
wait for each transfer to complete before starting the next. 

mapoperationcompleted (mapevent, map rc). This 
function processes the FTAM events by performing some action on the 
results of the FTAM operation that completed. The operation is 
identified by the map_event passed as input. If map_rc equals 
SUCCESS, the inout_dcbfor the operation contains the outcome of the 
operation. Otherwise, the map_rcequals EME032J PC_ERROR; the 
operation fails and the inout_dcb does not contain valid information. The 
specific actions involved with processing a completed FTAM event are 
specifictothe particular event, and could be as simpleas logging the 
results to an output file. 
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#include %<stdio.h> 

#include %</opt/ftam/include/map.h> 

#define BITS_PER_INT 32 

#define SET_MASK(f,fds) (fds)[((f)/BITS_PER_INT)] |= 

(1%<%< ( (f)%BITS_PER_INT) ) 

#define TST_MASK(f,fds) ((fds)[((f)/BITS_PER_INT)] & 

(1%<%< ( (f)%BITS_PER_INT) )) 
main() 


Bool 

Local_event_name 

Return_code 

Api_rc 

char 

char 

int 

unsigned 

/* Read and proce 
** outstanding at 


done; 

map_event; 
map_rc; 
map_result; 

*ret_str; 

*ven_str; 
nf ds; 

readfds[2]; /* handles upto 64 fds */ 

ss the first command. No FTAM operations are 
this time, so do not wait for any to complete. 


*/ 


done = read_and_process_command(); 

/* Wait indefinitely for MAP and non-MAP (i.e., stdin readable) events 
** to occur. If an EME032_IPC_ERROR occurs, the MAP operation 
** identified by map_event is treated as having completed with the IPC 
** error. Non-MAP events can also return in this case, so they 
** are processed as well. 

■k ~k 


** If any other error occurs, there is a programming error when calling 
** em_hp_select(); in this case, use em_gperror() and em_fdmemory() to 
** translate the error into printable character strings, then 
** abort processing so you can fix the coding error. 

■k ~k 

** Continue processing both FTAM and non-FTAM events until a "Quit" 
command 

** is entered as the non-FTAM event. 

*/ 
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while ( ! done ) 

{ 

readfds[0] = 0; 
readfds[1] = 0; 

SET_MASK(stdin, readfds); 
nfds — stdin + 1; 

map_rc = em_hp_select(FOREVER, & map_event, & nfds, readfds, NULL, 

NULL, 

& map_result); 

if ((map_rc == SUCCESS) I I (map_rc == EME032_IPC_ERROR)) 

{ 

if ((map_event !- 0)) 

map_operation_completed(map_event, map_rc); 
if (TST_MASK(stdin, readfds)) 
done = read_and_process_command() ; 

} 

else 

{ 

ret_str = NULL; 
ven_str = NULL; 

map_rc = em_gperror(& map_result, & ret_str, & ven_str, & 
map_result); 

if (map_rc == SUCCESS) 
fprintf(stderr, "%s%s", ret_str, ven_str); 
em_fdmemory(ret_str, & map_result); 
em_fdmemory(ven_str, & map_result); 
exit (1) ; 

} 

} /* while */ 

/* You finished entering commands, but all of the MAP operations may not 
** be complete. Since only MAP events are left, em_wait() is used instead 
** of em_hp_select(). An EMEO02_EXP_EMPTY result indicates all MAP 
** operations have completed. 

*/ 

done = FALSE; 
do { 

map_rc = em_wait(FOREVER, & map_event, & map_result); 
if ((map_rc == SUCCESS) I I (map_rc == EME032_IPC_ERROR)) 
map_operation_completed(map_event, map_rc); 
else if (map_rc == EME002_EXP_EMPTY) 
done - TRUE; 
else 
{ 

done = TRUE; 
ret_str = NULL; 
ven_str = NULL; 

map_rc = em_gperror(S map_result, & ret_str, & ven_str, & map_result); 
if (map_rc == SUCCESS) 
fprintf(stderr, "%s%s", ret_str, ven_str); 
em_fdmemory(ret_str, & map_result); 
em_fdmemory(ven_str, & map_result); 
exit (2); 

} 

} while ( ! done ); 
exit (0); 

} /* main */ 
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Handling Signal Interrupts 

Suppose an application needs the em_wait() function to return 
prematurely if a signal interrupt occurs. One case where this is 
applicable is when receipt of a signal should cause a new FTAM 
operation to be initiated or an outstanding operation to be aborted (e.g., 
the application is being terminated abruptly). Since FTAM functions are 
not reentrant, the application needs toforceem_wait()to return 
prematurely so the appropriate action can betaken upon receipt of the 
signal. 

Theem_wait() and em_hp_select() functions cannot detect signal 
interrupts and automatically return. However, you can cause 
em_hp_select() to return when interrupted by a signal. This involves 
translating the signal interrupt into an em_hp_select() non-FTAM event 
while executing the signal handler. When em_hp_select() resumes 
processing after the signal handler completes, the non-FTAM event will 
be detected and em_hp_select() will return. 

Several techniques exist to translate the signal interrupt into an 
em_hp_select() non-FTAM event. Oneway is to use an HP-UX pipe as 
follows: 

1. Open the pipe for both reading and writing within the application 
program. 

2. For the expected signals, install a signal handler that writes the 
trapped signal value to the pipe. This will cause the pipe to become 
readable. 

3. Replace calls to em_wait() (which waits for only FTAM events) with 
cal Is to em_hp_select(). I niti al i ze the readfds mask to i ncl ude the read 
descriptor for the pipe. If a signal interrupt occurs while executing or 
blocking within em_hp_select(), the pipe will become readable and 
cause em_hp_select() to return. 

4. After em_hp_select() returns, read the signal value from the pipe so 
that the notification will be cleared; then takethe appropriate action 
based on the signal value. 
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The following program example illustrates how to use em_hp_select() 
and an H P-UX pipe to implement the signal handling technique 
described previously. 


#include %<signal.h> 

#include %</opt/ftam/include/map.h> 

#define BITS_PER_INT 32 

#define SET_MASK(f,fds) (fds)[((f)/BITS_PER_INT)] |= 

(1%<%< ( (f)%BITS_PER_INT) ) 

#define TST_MASK(f,fds) ((fds)[((f)/BITS_PER_INT)] & 

(1%<%< ( (f)%BITS_PER_INT) )) 

#define READ 0 
#define WRITE 1 

int sig_pipe[2]; /* Pipe r/w descriptors used to queue signals */ 

void 

signal_handler(sigval) 
int sigval; 

{ 

/* Put signal on the pipe to make the pipe readable. This will cause 
** em_hp_select() to return. 

*/ 

write(sig_pipe[WRITE] , & sigval, sizeof (int)); 

/* Perform other signal handling logic if any. */ 

} 

main () 


int 

struct sigvec 

Local_event_name 

Return_code 

Api_rc 

int 

unsigned 

/* 


sigval; 

vec; 

map_event; 
map_rc; 
map_result; 
nf ds; 

readfds[2]; 


** Create the HP-UX pipe which is 
** into an em_hp_select() non-MAP 
*/ 

pipe (sig_pipe); 


/* The signal value read from pipe */ 
/* sigvector for installing handler */ 


/* MAP Event Name */ 

/* MAP return code */ 

/* MAP result structure */ 

/* File descriptor bound */ 

/* File descriptor mask */ 


used to translate the signal interrupt 
event. 
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/* Install the signal handler for the signal you want to trap. */ 
vec.sv_handler = signal_handler; 
vec.sv_mask = 0; 

vec.sv_flags = 0; 

sigvector(signal_you_want_to_trap, & vec, NULL); 

/* Initiate the asynchronous FTAM operations. The code for 
** initiating these operations is not shown in this example. 

*/ 

/* Wait for a MAP operation to complete or a signal to be caught. 

** This is done by blocking on both MAP events and the sig_pipe 
** to become readable. 

*/ 

readfds[0] = 0; 
readfds[l] = 0; 

SET_MASK(sig_pipe[READ], readfds); 
nfds = sig_pipe[READ] + 1; 

map_rc = em_hp_select(FOREVER, & map_event, & nfds, readfds, NULL, NULL, 

& map_result); 

if ((map_rc == SUCCESS) || (map_rc == EME032_IPC_ERROR)) 

{ 

if (map_event != 0) 

{ 

/* Process the results of the completed MAP operation. The 
** code for this function is not shown in this example. 

*/ 

map_operation_completed (map_event, map_rc) ; 

} 

if (TST_MASK(sig_pipe[READ], readfds)) 

{ 

/* em_hp_select() was interrupted by a signal. Remove the signal 
** value from the pipe to clear the interrupt notification. 

*/ 

read(sig_pipe[READ], & sigval, sizeof(int)); 

/* Perform the application specific logic to be done when 
** em_hp_select () unblocks because of a signal. 

*/ 

} 

} 

else 

{ 

/* Handle the em_hp_select() error. See Example 1. */ 

} 
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Using em_hp_sigio() 

#include %</opt/ftam/include/map.h> 
Return_code 

em_hp_sigio (action, pid, result) 
Unit32 action; 

Sint32 pid; 

Api_rc *result; 


This section describes how to useem_hp_select() and provides a program 
example. For additional details, refer to the HP FTAM/ 9000 Reference 
Manual. 

Useem_hp_sigio() to enable the MAP Event Management interface to 
generate SI Gl 0 signals whenever an asynchronous MAP event is 
pending. Uni ike the other MAP event management functions, 
em_hp_sigio() does not return a MAP event to the caller. I nstead, it 
merely puts the MAP event management interface into an extended 
capability mode. 

By using this capability, you can suspend the processing of your 
application until any of a variety of signals or semaphore operations 
cause your application to resume execution. Then, only after theSIGIO 
signal has been received do you need to call em_wait() to obtain the MAP 
event that is pending. Furthermore, since you know the MAP event is 
already pending, you can call em_wait() with a zero timeout to obtain the 
event and return immediately. 

The following program example illustrates one possible use of 
em_hp_sigio(). The program initiates and processes two types of events: 
MAP events in the form of FTAM and/or FTAM asynchronous 
operations, and Non-MAP events that taketheform of SI GUSR1 signals. 
The em_hp_sigio() function is used to enable SI GIO signal notification in 
the MAP Event Management interface, and em_wait() is used to process 
the MAP event after SI Gl 0 is caught. 
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/* 


Sample program for em_hp_sigio() 


** This program is designed with three primary components: 

** * a central control/dispatch component 

** * a MAP event processing component 

** * a Non-MAP event processing component 


** The central control/dispatch component makes use of an array of semaphores 
** to manage program suspension and resumption, and to keep track of which 
** components (MAP or Non-MAP) have work to do. Additionally, a signal 
** handler is installed for the MAP and Non-MAP generated signals which 
** manipulates the semaphore array. The SIGIO signal is used to notify the 
** control/dispatch component that a MAP event needs to be processed, and the 
** SIGUSR1 signal is used for Non-MAP events. 


** The MAP and Non-MAP processing components are referenced as external 
** functions. Details of these components are specific to each application 
** and are, therefore, not included here. Note, calling em_wait() to obtain 
** the MAP event would normally be included in the MAP specific processing 
** component, but em_wait() is pulled out into the main component here to 
** demonstrate the relationship between em_hp_sigio() and em_wait(). 

*/ 

#include %<stdio.h> 

#include %<errno.h> 

#include %<signal.h> 

#include %<sys/types.h> 

#include %<sys/ipc.h> 

#include %<sys/sem.h> 

#include %</opt/ftam/include/map.h> 

/* 

** Functions and variables not provided by the demonstration program. 

*/ 

extern Bool operations_to_wait_on_and_process; 
extern void initiate_MAP_operation(); 
extern void process_MAP_operation(); 
extern void initiate_NON_MAP_operation(); 
extern void process_NON_MAP_operation(); 

/* 

** Semaphores used to manage suspend/resume activity 

•k k 


** Three semaphores are used to manage the MAP and Non-MAP asynchronous 
** activity. One semaphore is used to control the suspension and resumption 
** of process. Another semaphore is used to keep track of the number of 
** pending events for each event type, MAP and Non-MAP in this case. 

k k 

** The semaphores are operated on by a set of functions included following 
** the main program. The functions provide logical P and V operations on a 
** set of semaphores, based on HP-UX semaphore operations (system calls). 

*/ 


tdefine NUM_SEMAPHORES 3 
tdefine SEM_CONTROL 1 

tdefine SEM_MAP 2 

tdefine SEM_NON_MAP 4 


/* Used for suspend & 
/* Used to track pendi 
/* Used to track pendi 


resume control */ 

g MAP events */ 

g Non-MAP events */ 
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#define WAIT 
#define NO_WAIT 
int sem_id; 
int sem_create() ; 
void sem_remove() ; 
int sem_p(); 
void sem_v(); 

/* 

** Signals and signal 
** The signal_handler 
*/ 

tdefine SIG_MAP 
tdefine SIG_NON_MAP 
void signal_handler(); 

/* 

•k 

*/ 

main() 


0 /* Tells sem_p)) to block if necessary */ 

1 /* Tells sem_p() to return immediately */ 

/* The semaphore array for async mgmt */ 

/* Create semaphores on the system */ 

/* Remove semaphores from the system */ 

/* Perform a P (get) operation */ 

/* Perform a V (give) operation */ 


handler used to manage asynchronous event notification, 
logic is included following the main program. 

SIGIO /* MAP notification signal */ 

SIGUSR1 /* Non-MAP signal (for example) */ 

/* Signal handler for async event mgmt */ 

MAIN PROGRAM 


Local_event_name 

Return_code 

Api_rc 

struct sigvec 


map_event_name; /* 
map_rc; /* 
map_result; /* 
vec; /+ 


printf("Demonstration program for em_hp_sigio()\n"); 
/* 


MAP 3.0 event name (identifier) 
MAP 3.0 function return code 
MAP 3.0 result structure 
Signal Vector for event handler 


** Create and initialize the semaphore array for process suspension and 
** resumption. 

*/ 

printf ("Creating semaphore for process suspend & resume.\n"); 
sem_id = sem_create(NUM_SEMAPHORES); 

/* 

** Install the signal handler to catch interrupts for each signal used 
** as an event notification. 


*/ 

printf("Installing signal handlers for MAP and Non-MAP events\n"); 
vec.sv_handler = signal_handler; 
vec.sv_mask = 0; 

vec.sv_flags = 0; 

sigvector(SIGIO, & vec, NULL); /* MAP events */ 

sigvector(SIGUSR1, & vec, NULL); /* Non-MAP events */ 

/* 


** Put the MAP 3.0 Interface into SIGIO notification mode. This causes 
** MAP Event Management to generate a SIGIO signal whenever there is 
** an asynchronous event to process. 

:k -k 


/ 

/ 

/ 

/ 


** Note, the process to signal is the local (this) process. The process 
** id is negated to distinguish it from a process group id. 

*/ 

printf ("Calling em_hp_sigio() to enable SIGIO notification for MAP.\n"); 
map_rc = em_hp_sigio(EM_SIGIO_ENABLE, getpid(), & map_result); 
if (map_rc != SUCCESS) 


fprintf(stderr, "ERROR: em_hp_sigio(ENABLE) failed, %d\n", map_rc); 
exit (1) ; 
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/* 

** Activate MAP 3.0 Application Entity for FTAM or FTAM, then initiate 
** asynchronous MAP 3.0 operations. 

*/ 

initiate_MAP_operation() ; 

/* 

** Initialize and initiate Non-MAP asynchronous operations. 

*/ 

initiate_NON_MAP_operation(); 

while (operations_to_wait_on_and_process) 

{ 

/* 

** Suspend processing until an asynchronous event occurs. 

*/ 

printf("\nSuspending processing until an event occurs.\n"); 
sem_p(sem_id, SEM_CONTROL, WAIT); 

/* 

** Processing has resumed. Determine the event type that occurred. 

*/ 

printf(''Resuming processing after semaphore popped.\n"); 

/* 

** Process MAP 3.0 (FTAM or FTAM) event if one is pending. 

~k 

** A non-blocking sem_p() operation is used to atomically test and 
** decrement the pending MAP event count. If a MAP event is pending, 
** sem_p() returns zero; otherwise, it returns non-zero. 

•k k 

** Note, calling em_hp_sigio() earlier merely put the MAP interface 
** into SIGIO notification mode. You must still call em_wait() to 
** obtain the event name for the MAP 3.0 operation that triggered 
** the signal notification. Furthermore, the operation may only be 
** partially complete. Calling em_wait() processes the MAP event as 
** much as possible, but returns EME005_TIMEOUT if the event is not 
** completely processed. 

*/ 

if (sem_p(sem_id, SEM_MAP, NO_WAIT) == 0) 

{ 

printf("Calling em_wait() to obtain MAP event.\n"); 
map_rc = em_wait(0, & map_event_name, & map_result); 
if (map_rc == SUCCESS) 

process_MAP_operation(map_event_name) ; 
else if (map_rc == EME005_TIMEOUT) 

printf("em_wait timeout: operation partially complete\n"); 

else 

fprintf(stderr, "ERROR: em_wait() failed, %d\n", map_rc); 

} 
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/* 

** Process Non-MAP event if one is pending. 

** A non-blocking sem_p() operation is used to atomically test and 
** decrement the pending Non-MAP event count. If a Non-MAP event is 
** pending, sem_p() returns zero; otherwise, it returns non-zero. 

•k k 

** Note, event processing is specific to your own application; 

** details are not included in this example. 

*/ 

if (sem_p(sem_id, SEM_NON_MAP, NO_WAIT) == 0) 

{ 

process_NON_MAP_operation(); 

} 

} /* while - operations to process */ 

/* 

** Disable SIGIO notification for the MAP 3.0 Interface. 

** Note, the process id parameter is ignored so any value is fine. 

*/ 

printf("\nCalling em_hp_sigio() to disable SIGIO notification.\n"); 
map_rc = em_hp_sigio(EM_SIGIO_DISABLE, 0, & map_result); 
if (map_rc != SUCCESS) 

fprintf(stderr, "ERROR: em_hp_sigio(DISABLE) failed, %d\n", map_rc); 

/* 

** Remove semaphore resources. 

*/ 

printf ("Cleaning up semaphore resources.\n") ; 
sem_remove(sem_id); 
exit (0); 

} /* end main() */ 

/* 

** Signal Handler for Event Notification 

~k k 

** The event notification signal handler performs a semaphore V operation 
** on the suspend/resume semaphore, plus the specific event type semaphore. 
*/ 

void 

signal_handler(sig) 
int sig; 

{ 

unsigned long sem_mask; 

printf("Signal handler taken for signal %d\n", sig); 

/* 

** Always included the Control semaphore in the semaphore mask. This is 
** what causes the main program to resume execution. 

*/ 

sem_mask = SEM_CONTROL; 
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/* 

** Determine the event type based on the signal received. 

** Update the semaphore mask to include the event type specific 
** semaphore. 

*/ 

if (sig == SIG_MAP) 

sem_mask |= SEM_MAP; 
else if (sig == SIG_NON_MAP) 
sem_mask |= SEM_NON_MAP; 
else { 

fprintf(stderr, "ERROR: unsupported signal, %d\n", sig); 
exit (1); 


/* 

** Perform a V (give) operation on the specified semaphores so that the 
** process can resume (if suspended), and the event count for the given 
** type is incremented atomically. 

*/ 

sem_v(sem_id, sem_mask); 

} /* signal_handler */ 

/* 

** sem_create() 

:k ~k 

** This function creates a semaphore array for the specified number of 
** semaphores (up to 32) and initializes them to an "unblocked" state. 

*/ 

int 

sem_create(sem_cnt) 
int sem_cnt; 

{ 

int sem_id; 

ushort sem_val[sizeof(unsigned long)]; 

sem_id = semget(IPC_PRIVATE, sem_cnt, IPC_CREAT | 0600); 

if (sem_id == -1) 

{ 

fprintf(stderr, "ERROR: creating semaphore, errno %d\n", errno); 
exit (1); 

} 

memset(sem_val, 0, sizeof(sem_val)); 
if (semctl(sem_id, 0, SETALL, sem_val) == -1) 

{ 

fprintf(stderr, "ERROR: initializing semaphore, errno %d\n", errno); 
exit(1); 

} 

return(sem_id) ; 

} 


Chapter 4 


193 



Using Support Functions 

Responding to Asynchronous Calls 


/* 

** sem_remove() 

•k k 

** This function removes the semaphore array from the system. 

*/ 

void 

sem_remove (sem_id) 
int sem_id; 

{ 

if (semctl(sem_id, 0, IPC_RMID, 0) == -1) 

{ 

fprintf(stderr, "ERROR: removing semaphore, errno %d\n", errno); 
exit(1); 


k 

** This function performs a semaphore P (get) operation on the set of 
** semaphores specified by 'sem_mask'. The sem_mask is defined such that 
** semaphore number N is represented by bit (1 %< (N-l)) in the mask. 

k 

** If the 1 sem_nowait' flag is FALSE, processing is suspended until blocking 
** conditions for all of the specified semaphores have cleared. 

** If the 'sem_nowait' flag is TRUE, processing continues immediately and the 
** return value indicates whether a blocking condition exists or not. 

k k 

** If all blocking conditions are cleared, the function returns zero. 

** Otherwise, non-zero returns. 

*/ 

int 

sem_p(sem_id, sem_mask, sem_nowait) 
int sem_id; 

unsigned long sem_mask; 
int sem_nowait; 


struct sembuf sem_ops[sizeof(unsigned long)]; 

int sem_num = 0; 

int sem_cnt = 0; 

int rc =0; 

while ((sem_num %< sizeof(unsigned long)) & & sem_mask) 

{ 

if (sem_mask & 1) 


} 


sem_ops[sem_cnt].sem_num 
sem_ops[sem_cnt].sem_op 
sem_ops[sem_cnt].sem_flg 
sem_cnt++; 

} 

sem_num++; 

sem_mask >= 1; 


sem_num; 

- 1 ; 

(sem_nowait ? IPC_NOWAIT : 0); 
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if (sem_cnt > 0) 


do { 

rc = semop(sem_id, sem_ops, sem_cnt); 

} while ((rc == -1) & & (errno == EINTR)); 

if ((rc == -1) & & !((sem_nowait) & & (errno == EAGAIN))) 

{ 

fprintf(stderr, "ERROR: semaphore P (get), errno %d\n", errno); 
exit(1); 

} 

} 

return(rc); 

} /* sem_p */ 


** This function performs a semaphore V (give) operation on the set of 
** semaphores specified by 1 sem_mask'. The sem_mask is defined such that 
** semaphore number N is represented by bit (1 %< (N-l)) in the mask. 

*/ 

void 

sem_v(sem_id, sem_mask) 
int sem_id; 

unsigned long sem_mask; 

{ 


struct sembuf 

int 

int 

int 

while ((sem_num %< 


sem_ops[sizeof(unsigned long)]; 
sem_num = 0; 
sem_cnt = 0; 
rc; 

sizeof(unsigned long)) & & sem_mask) 


if (sem_mask & 1) 

{ 

sem_ops[sem_cnt].sem_num 
sem_ops[sem_cnt].sem_op 
sem_ops[sem_cnt].sem_flg 
sem_cnt++; 

} 

sem_num++; 
sem_mask >= 1; 


sem_num; 

1 ; 

0 ; 


if (sem_cnt > 0) 

{ 

do { 

rc = semop(sem_id, sem_ops, sem_cnt); 

} while ((rc == -1) & & (errno == EINTR)); 

if (rc == -1) 

{ 

fprintf(stderr, "ERROR: semaphore V (give), errno %d\n", errno); 
exit(1); 

} 

} 

} /* sem_v */ 
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Translating Error Messages 

FTAM and Event Management functions return Return_codes. 

• To translate errors returned by Event Management to character 
strings, invokeem_gperror(). 

• To translate errors return by FTAM functions to character strings, 
invoke ft_gperror(). 

emgperrorO 

#include %</opt/ftam/include/map.h> 

Return_code 

em_gperror(input_result, return_string, vendor_string, result) 
Api_rc *input_result; 

Octet **return_string; 

Octet **vendor_string; 

Api_rc ^result; 


Theem_gperror() function translates the input_result structure from 

Event Management functions to character strings, as follows: 

• The input_result->return_code is translated to a character string 
called return_string. 

• The input_result->vendor_code is translated to a character string 
called vendor_string. 

• If the address that the return_string points tois NULL, theinterface 
automatically allocates the required memory. After em_gperror() 
returns, you must use em_fdmemory() to free the memory. Do not use 
free() to deal locate memory allocated by FTAM. 

• If the address that the return_string points to is not NULL, the value 
must be the address of the memory that was previously al located. The 
specified data area must be large enough to hold a 256-byte string 
(including the NULL-terminator). 

• You may receive unpredictable results if using free() for memory 
allocated by em_gperror(). 


196 


Chapter 4 




Using Support Functions 

Translating Error Messages 


em_gperror() Parameters 


em_gperror() 

Parameter 

Type 

Description 

input_result 

Mandatory 

1 nput 

Poi nter to the Api_rc structure contai ni ng 
information to translate: return_code (MAP 3.0 error) 
and vendor_code (HP- UX—specific error) 

return_string 

Mandatory 

1 nput 

Address of where topi ace the character stri ng for 
input_result->return_code 


Output 

Address of the return_code character string; this 
string is NULL terminated and already contains the 
NEW LINE character 

vendor_string 

Optional 1 nput 

Address of where topi ace the character stri ng for 
input_result->vendor_string 


Output 

Address of the vendor_code character stri ng; this 
string is NULL terminated and already contains the 
NEW LINE character 

result 

Output 

Pointer to the Api_rc structure containing outcome of 
the operation: return_code (MAP 3.0 error) and 
vendor_code (H P-UX—specific error) 
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ft_gperror() 

#include %</opt/ftam/include/map.h> 

Return_code 

ft_gperror (input_result, return_string, vendor_string, result) 
Api_rc *input_result; 

Octet **return_string; 

Octet **vendor_string; 

Api_rc ^result; 


Theft_gperror() function translates the input_result structure from 

FTAM functions to character strings, as follows: 

• The input_result->return_code is translated to a character string 
called return_string. 

• The input_result->vendor_code is translated to a character string 
called vendor_string. 

• If the address that the return_string points tois NULL, theinterface 
automatically allocates the required memory. After ft_gperror() 
returns, you must useft_fdmemory() to free the memory. 


NOTE Do not usefreeQ to deallocate memory allocated by FTAM. 


• If the address that the return_string points to is not NULL, you must 
allocate the memory. The specified data area must be large enough to 
hold a 256-byte string (including the NULL-terminator). 
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ft_gperror() 

Parameter 

input_result 

return_string 


vendor_stri ng 


result 


ft_gperror() Parameters 


Type 

Description 

Mandatory 

1 nput 

Pointer to the Api_rc structure containing 
information to translate: return_code (MAP 3.0 error) 
and vendor_code (H P- U X—specific error) 

Mandatory 

1 nput 

Address of where to place the character string for 
i n put_resul t->retu rn_code 

Output 

Address of the return_code character string; this 
string is NULL terminated and already contains the 
NEW LINE character 

Optional Input 

Address of where to place the character string for 
i n put_resu 11- >vendor_st r i ng 

Output 

Address of the vendor_code character string; this 
string is NULL terminated and already contains the 
NEW LINE character 

Output 

Pointer tothe Api_rc structure containing outcome of 
the operation: return_code (MAP 3.0 error) and 
vendor_code (HP-UX—specific error) 
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Determining Available Resources 

While sending data, limited flow control resources may prevent the 
operation from completing. This circumstance is indicated by the error 
FTE008_NO_CON_RESOURCES returning on ft_sdata() function calls. 
To determine when the resource clears, call ft_nwcleared(). 

ft nwclearedO 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_nwcleared (connection_id, local_event_name, inout_dcb) 
Connection_id connection_id; 

Local_event_name local_event_name; 

struct Ft_nwcleared_out_dcb **inout_dcb; 


Useft_nwcleared() todetermine when the 

FTE008_NO_CON_RESOURCES error condition (on ft_sdata()) clears 

and there are enough resources to continue. 

• Theft_nwcleared() connectionjd must be the same as the connection 
that returned the FTE008_NO_CON_RESOURCES error. 

• If you invoke ft_nwcleared() synchronously, the function does not 
return until a resource is acquired. Though resources clear, there is 
no guarantee they will be availablefor a subsequent ft_sdata() 
request. 

• If you invoke ft_nwcleared() asynchronously, you cannot call other 
functions on that connectionjd until theft_nwcleared() is noted by 
em_wait(). If you call another function beforeft_nwcleared() is noted, 
you are not informed when the resource is available (i.e., the 
ft_nwcleared() is revoked). 

• When cal I i ng ft_sdata() a second ti me, all parameters must be the 
same as those of the i niti al ft_sdata() request. 
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EXAMPLE: This example shows the use of ft_nwcleared(). The 

connectionjd and data_unit parameters were 
previously set. 


Connection_id 
struct Ft_data_unit 
Local_event_name 
struct Ft_sdata_out_dcb 
struct Ft_nwcleared_out_dcb 
Result_code 

sda_event_name = 1; 
sda_inout_dcb = NULL; 
res = ft_sdata(connection_id, & data_unit, sda_event_name, & sda_inout_dcb); 
if (res == FTE008_NO_CON_RESOURCES) { 
nwc_event_name = 0; 
nwc_inout_dcb = NULL; 

res = ft_nwcleared(connection_id, nwc_event_name, & nwc_inout_dcb); 
if (res == SUCCESS) { 

res = ft_sdata(connection_id, & data_unit, sda_event_name, 

& sda_inout_dcb); 



connection_id; 
data_unit; 

sda_event_name, nwc_event_name; 
*sda_inout_dcb; 

*nwc_inout_dcb; 
res; 


ft_nwcleared() Parameters 


ft_nwcleared() 

Parameter 

Type 

Description 

connection_id 

Mandatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

local_event_na 

me 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value is 0 
(zero) 

inout_dcb.size 

Mandatory 
input if using 
i nout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb.result 

Output 

Poi nter to the struct Api_rc contai ni ng the outcome 
of the operation: result_code (MAP 3.0 error) and 
vendor_code (H P-UX—specific error) 
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High level functions simplify FTAM programming by performing a series 
of low level functions for you. Since the high level functions described in 
this chapter are context free, you can usethem at anytime. Applications 
written with high level, context free (H LCF) functions are smaller, easier 
to write, and less prone to error. 

Refer to the "Example Programs" chapter for model programs using the 
HLCF functions. 
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C hapter Overview 

This chapter describes the foil owing H LCF functions in the order listed. 


Task to Perform 

Function Used to 
Perform the Task 

Description 

Copying and Moving FTAM Files 

ft_fcopy() 

ft_fcopy_aet() 

Copy files 


ft_fmove_aet() 

ft_fmove() 

Movefiles 

Reading and Changing Attributes 

ft frattributesO 
ft_frattri butes_aet() 

Read attributes 


ft_fcattributes() 
ft_fcattri butes_aet() 

Change attributes 

Deleting Files 

ft_fdelete() 

ft_fdelete_aet() 

Delete files 


NOTE This chapter does not explain the parameter structures. For detailed 

structure information (parameter settings), refer tothe "FTAM Data 
Structures" chapter. 
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Copying and Moving FTAM Files (HLCF) 

Use ft_fcopy() and ft_fcopy_aet() to copy files, and ft_fmove() and 
ft_fmove_aet() to movefiles with onlyonecall. Since copying or moving 
files using low level calls requires most FTAM functions, you can save 
significant coding time and effort using ft_fcopy(), ft_fcopy_aet(), 
ft_fmove(), and ft_fmove_aet(). 


ftfcopyO 


#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
Return_code 


ft_fcopy(source_dirname, source. 

destination_filename, 
input_dcb, inout_dcb) 
Ae_dir_name 
Ft_filename 
Ae_dir_name 
Ft_filename 
Ae_label 

Local_event_name 
struct Ft_fcopy_in_dcb 
struct Ft_fcopy_out_dcb 


ilename, destination_dirname, 
e_label, return_event_name, 

source_dirname; 
source_filename; 
destination_dirname; 
destination_filename; 
*ae_label; 
return_event_name; 
*input_dcb; 

**inout_dcb; 


Theft_fcopy() function copies one FTAM file (contents and attributes) to 
another FTAM file. The original file remains in tact. The new file 
contains the source file attributes and those attributes that are 
automatically set (e.g., filesize). 

• If thefileyou are copying to already exists, the outcome depends on 
how you set input_dcb-overwrite. If input_dcb->overwrite is set to 
FT_RECREATE_FI LE, FTAM copies the source file over the existing 
destination file. If the value is FT_DONT_RECREATE_FI LE, FTAM 
does not copy the source file over the existing file, the function fails, 
and you receive an error message. 


NOTE The following points do not apply to H P-UX FTAM responders. H P-UX 

FTAM responders do not use these fields. The information is provided 
here because other implementations may use these fields. 
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• If the file has access control elements, and an identity field matches 
thesourcejnitjd, the input_dcb->src_concur_cntl must be a subset 
of the val ues stored i n the conc_access field of struct 

F t_access_control_element. 

• If the file has access control elements, and an identity field matches 
thedestjnitjd, the input_dcb->dest_concur_cntl must be a subset of 
the values stored in the conc_access field of struct 

F t_access_control_element. 

• You must supply matching passwords in input_dcb- 
>source_file_passwords for FT_FA_READ and 
FT_FA_READ_ATTRI BUTE file actions if the following conditions 
exist. 


• If thefileyou are copying from contains an identity (in 
Ft_access_control_element) that matches the sourcejnitjd AN D 

• If passwords exist for these file actions 

• You must supply matching passwords in input_dcb- 

>dest_file_passwords if thefileyou copying to exists and contains an 
identity (in Ft_access_control_element) that matches the destjnitjd 
and if passwords exist for these file actions. 

• If the file is an FTAM-1, FTAM-3, or INTAP-1 document type, you 
must supply matching passwords for FT_FA_DELETE_FI LE and 
FT_FA_REPLACE. 

• If the file is an FTAM-2 document type, you must supply 
matching passwords for FT_FA_DELETE_FI LE and 

FT FA INSERT. 


F tfcopyi ndcb 


struct Ft_fcopy_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_single_file_pw 
enum Ft_delete_overwrite 
struct Ft_concurrency_control 
struct Ft_concurrency_control 


source_init_id; 
source_filestore_pw; 
source_account; 
source_file_passwords; 
dest_init_id; 
dest_filestore_pw; 
dest_account; 
dest_file_passwords; 
create_file_pw; 
overwrite; 
*src_concur_cnt1; 
*dest_concur_cntl; 
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F tfcopyou t_dc b 

struct Ft_fcopy_out_dcb { 
Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_attributes 
struct Ft_charging 
struct Ft_diagnostic 

} ; 


size; 

result; 

action_result; 
attributes; 
*charging; 
*diagnostic; 


ft fcopyO Parameters 


ft_fcopy() 

Parameter 

Type 

Description 

sou rce_dir name 

Optional 1 nput 

Directory distinguished name of the source 
filestore; NULL implies local filestore 

source_filename 

Mandatory 

1 nput 

Path name of the file you are copying; must be in 
the syntax of the real filestore 

desti nati on_di rname 

Optional 1 nput 

Di rectory disti nguished name of the desti nation 
filestore; NULL implies local filestore 

dest i n at i on_fi 1 en a me 

Optional 1 nput 

Path name of the file to which you are copying; 
NULL implies source_filename; must be in the 
syntax of the real filestore 

aejabel 

Mandatory 

1 nput 

Unique identifier of ftamjnit you want to 
service the request; if pointing to a NULL 
location, the interface uses a currently activated 
ftamjnit or activates and deactivates a 
ftamjnit 


Output 

Unique identifier for ftamjnit that serviced the 
request 

r et u r n_event_n a me 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb-> 

Optional 1 nput 

Source login account 


source init id 
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ft_fcopy() 

Parameter 

Type 

Description 

input_dcb-> 
sou rce_fi 1 estore_pw 

Optional 1 nput 

Login password for thesourcejnitjd account 

input_dcb-> 

source_account 

Optional 1 nput 

Identifies who is responsible for accumulated 
storage charges on source file; HP-UX 
responders accept, but ignore, this value. 

input_dcb-> 

sou rce_fi 1 e_passwords 

Optional 1 nput 
(Used only with 
non-HP-UX 
responders.) 

Structure containing the passwords for 

FT FA READ and 

FT_FA_READ_ATTRI BUTE. Set 
source_file_passwords only if the file you are 
copying from has an identity (in 
Ft_access_control_element) that matches 
sourcejnitjd and if passwords exist for these 
two actions 

input_dcb- 

>dest_init_id 

Optional 1 nput 

Destination login account 

input_dcb-> 

dest_filestore_pw 

Optional 1 nput 

Login password for thedestjnitjd account 

input_dcb-> 

dest_account 

Optional 1 nput 

Identifies who is responsible for accumulated 
storage charges on destination file; HP-UX 
responders accept, but ignore, this value. 

input_dcb-> 
dest_fi 1 e_passwords 

Optional 1 nput 
(Used only with 
non-HP-UX 
responders.) 

Structure containing the passwords for the 
actions FT FA DELETE FILE (FTAM-1, 
FTAM-2, FTAM-3, INTAP-1), FT FA INSERT 
(FTAM-2), and FT_FA_REPLACE (FTAM-1, 
FTAM-3, INTAP-1). Set dest_file_passwords 
only if the file has an identity (in 
Ft_access_control_element) that matches 
destjnitjd and if passwords exist for these 
actions 

input_dcb-> 

create_file_pw 

Optional 1 nput 

Establishes permission to create files in the 
destination filestore 

input_dcb-overwrite 

Optional 1 nput 

Determines action taken if the destination file 


exists 
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ft_fcopy() 

Parameter 

Type 

Description 

input_dcb-> 

src_concur_cntl 

Optional 1 nput 
(Used only with 
non-HP-UX 
responders.) 

Sets the concurrency control for 
source_filename; compared toconc_access in 
struct Ft_access_control_element if an identity 
field matches the sourcejnitjd 

input_dcb-> 

dest_concur_cntl 

Optional 1 nput 
(Used only with 
non-HP-UX 
responders.) 

Sets the concurrency control for 
destination_filename; compared to conc_access 
in struct Ft_access_control_element if an 
identity field matches the destjnitjd 

inout_dcb->5ize 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code (MAP 3.0 
error) and vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

i nout_dcb->attri butes 

Output 

Contains values of the attributes that uniquely 
identify the destination file 

i nout_dcb->chargi ng 

Output 

HP-UX responders do not use charging, though 
it may contain information from other 
responders 

i n out_dcb- >d i agn ost i c 

Output 

Provides 1 SO-specificerror information 
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ftfmoveO 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_fmove(source_dirname, source_fi 
destination_filename, ae. 
input_dcb, inout_dcb) 
Ae_dir_name 
Ft_filename 
Ae_dir_name 
Ft_filename 
Ae_label 

L o c al_event_n ame 
struct Ft_fmove_in_dcb 
struct Ft_fmove_out_dcb 


ename, destination_dirname, 
.label, return_event_name, 

source_dirname; 
source_filename; 
destination_dirname; 
destination_filename; 
*ae_label; 
return_event_name; 
*input_dcb; 

**inout_dcb; 


The ft_fmove() function moves a file from one filestore to another (i.e., 
moves source_filename i n the source_di rname fiIestore to 
destination_filename in the destination_dirname filestore). The new file 
contains the source file attributes and those attributes that are 
automatically set (e.g., filesize). 

• If the file you are moving to already exists, the outcome depends on 
how you set input_dcb-overwrite. If input_dcb-overwrite is set to 
FT_RECREATE_FI LE, FTAM copies the source file over the existing 
destination file. If the value is FT_DONT_RECREATE_FI LE, FTAM 
does not copy the source file over the existing file, the fundi on fails, 
and you receive an error. 


NOTE The following points do not apply to H P-UX FTAM responders. H P-UX 

FTAM responders do not use these fields. The information is provided 
here because other implementations may use these fields. 


• If the file has access control elements, and an identity field matches 
thesourcejnitjd, the input_dcb->src_concur_cntl must be a subset 
of the values in the conc_access field of the access control element. 

• If the file has access control elements, and an identity field matches 
thedestjnitjd, the input_dcb->dest_concur_cntl must be a subset of 
the values in the cone access field of the access control element. 
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• You must supply matching passwords in input_dcb->source_file_ 
passwords for FT_FA_READ, FT_FA_READ_ATTRI BUTE, and 
FT_FA_DELETE_FI LE file actions if the foil owing conditions exist. 

• If thefileyou are moving contains an identity (in 
Ft_access_control_element) that matches the sourcejnitjd AN D 

• If passwords exist for these file actions 

• You must supply matching passwords in input_dcb- 
>dest_file_passwords if thefileyou moving to exists and contains an 
identity (in Ft_access_control_element) that matches the destjnitjd 
and if passwords exist for these file actions. 

• If the file is an FTAM-1, FTAM-3, or INTAP-1 document type, 
you must supply matching passwords for FT_FA_DELETE_FI LE 
and FT_FA_REPLACE. 

• If the file is an FTAM-2 document type, you must supply 
matching passwords for FT_FA_DELETE_FI LE and 
FT_FA_I NSERT. 

F tfmovei ndcb 

struct Ft_fmove_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_single_file_pw 
enum Ft_delete_overwrite 
struct Ft_concurrency_control 
struct Ft_concurrency_control 


source_init_id; 
source_filestore_pw; 
source_account; 
source_file_passwords; 
dest_init_id; 
dest_filestore_pw; 
dest_account; 
dest_file_passwords; 
create_file_pw; 
overwrite; 
*src_concur_cntl; 
*dest_concur_cntl; 


F tfmoveoutdcb 


struct Ft_fmove_out_dcb { 

Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_attributes 
struct Ft_charging 
struct Ft_diagnostic 

} ; 


size; 

result; 

action_result; 
attributes; 
*charging; 
*diagnostic; 
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ft_fmove() Parameters 


ft_fmove() 

Parameter 


Type 


Description 


sou rce_dir name 

Optional Input 

Directory distinguished name of the source 
filestore; NULL implies local filestore 

source_filename 

Mandatory 

1 nput 

Path name of the file you are moving; must be 
in the syntax of the real filestore 

desti nation_di rname 

Optional Input 

Directory distinguished name of the 
destination filestore; NULL implies local 
filestore 

dest i n at i on_fi 1 en a me 

Optional Input 

Path name of the file to which you are moving; 
NULL implies source_filename; must be in the 
syntax of the real filestore 

aejabel 

Mandatory 

1 nput 

Uniquely identifier of ftamjnit you want to 
service the request; if pointing to a NULL 
location, the interface uses a currently 
activated ftamjnit or activates and deactivates 
a ftamjnit 


Output 

Uniquely identifier for ftamjnit that serviced 
the request 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb-> 

sourcejnitjd 

Optional Input 

Source login account 

input_dcb-> 
sou rce_fi 1 estore_pw 

Optional Input 

Login password for the sourcejnitjd account 

input_dcb-> 

source_account 

Optional Input 

Identifies who is responsible for accumulated 
storage charges on source file; H P-UX 


responders accept, but ignore this value 
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ft_fmove() 

Parameter 

Type 

Description 

input_dcb-> 

sou rce_fi 1 e_passwords 

Optional 1 nput 
(Used only 
with non—H P- 
UX 

responders.) 

Structure contai ni ng the passwords for 

FT FA READ, FT FA READ ATTRIBUTE, 
and FT_FA_DELETE_FILE. Set 
source_file_passwords only if thefileyou are 
moving has an identity (in 
Ft_access_control_element) that matches 
sourcejnitjd and if passwords exist for these 
three actions 

input_dcb-> 

destjnitjd 

Optional 1 nput 

Destination login account 

input_dcb-> 

dest_filestore_pw 

Optional 1 nput 

Login password for the destjnitjd account 

input_dcb-> 

dest_account 

Optional 1 nput 

Identifies who is responsible for accumulated 
storage charges on destination file; HP-UX 
responders accept, but ignore, this value 

input_dcb-> 
dest_fi 1 e_passwords 

Optional Input 
(Used only 
with non-H P- 
UX 

responders.) 

Structure containing the passwords for the 
actions FT FA DELETE FILE (FTAM-1, 
FTAM-2, FTAM-3, INTAP-1), FT FA INSERT 
(FTAM-2), and FT_FA_REPLACE (FTAM-1, 
FTAM-3, 1NTAP-1). Set dest_file_passwords 
only if the file has an identity (in 
Ft_access_control_element) that matches 
destjnitjd, and if passwords exist for these 
actions 

input_dcb-> 

create_file_pw 

Optional Input 

Establishes permission to create files in the 
destination filestore 

i n pu t_dcb- >over w rite 

Optional Input 
(Used only 
with non—H P- 
UX 

responders.) 

Determines action taken if the destination file 
exists 
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ft_fmove() 

Parameter 

Type 

Description 

input_dcb-> 

src_concur_cntl 

Optional Input 
(Used only 
with non—H P- 
UX 

responders.) 

Sets the concurrency control for 
source_filename; compared to conc_access in 
struct Ft_access_control_element if an identity 
field matches the sourcejnitjd 

input_dcb-> 

dest_concur_cntl 

Optional Input 
(Used only 
with non—H P- 
UX 

responders.) 

Sets the concurrency control for 
destination_filename; compared to conc_access 
in struct Ft_access_control_element if an 
identity field matches the destj nitjd 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (i n Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 


outcome of the operation: result_code (MAP 3.0 
error) and vendor_code (HP-UX—specific 
error) 


inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

i nout_dcb->attri butes 

Output 

Contai ns val ues of the attri butes that uniquely 
identify the destination file 

i nout_dcb->chargi ng 

Output 

HP-UX responders do not use charging, though 
it may contain information from other 
responders 

i nout_dcb->di agnosti c 

Output 

Provides 1 SO-specificerror information 
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NOTE 


ftfcopyaet 


#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
Return_code 

ft_fcopy_aet(source_ascii_ddn, source_f 
destination_ascii_ddn, dest 
ae_label, return_event_name 

char 

Ft_filename 
char 

Ft_filename 
Ae_label 

Local_event_name 
struct Ft_fcopy_in_dcb 
struct Ft_fcopy_out_dcb 


ilename, 

ination_filename, 

, input_dcb, inout_dcb) 
*source_ascii_ddn; 
source_filename; 
*destination_ascii_ddn; 
destination_filename; 
*ae_label; 
return_event_name; 
*input_dcb; 

**inout_dcb; 


Theft_fcopy_aet() function copies one FTAM file (contents and 
attributes) to another FTAM file. The original file remains intact. The 
new file contains the source file attributes and those attributes that are 
automatically set (e.g., filesize). 


• Both ft_fcopy_aet() and ft_fcopy() can be used for copying files. 
However, ft_fcopy_aet() sends both the called AE title and calling AE 
title to the remote system while ft_fcopy() sends only the cal ling AE 
title. Also, in ft_fcopy_aet(), the DDN is passed directly as an ASCI I 
string without any conversion while in ft_fcopy(), the DDN must be 
converted and passed as an Ae_dir_name. 

• Ifthefileyou are copying to already exists, the outcome depends on 
how you set input_dcb-overwrite. If input_dcb-overwrite is set to 
FT_RECREATE_FI LE, FTAM copies the source file over the existing 
destination file. Ifthevalueis FT_DONT_RECREATE_FILE, FTAM 
does not copy the source file over the existing file, the fundi on fails, 
and you receive an error message. 


The following points do not apply to H P-UX FTAM responders. H P-UX 
FTAM responders do not use these fields. The information is provided 
here because other implementations may use these fields. 


• If the file has access control elements, and an identity field matches 
thesourcejnitjd, the input_dcb->src_concur_cntl must be a subset 
of the values stored in the conc_access field of strud 
Ft access control element. 
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• If the file has access control elements, and an identity field matches 
thedestjnitjd, the input_dcb->dest_concur_cntl must be a subset of 
the values stored in the conc_access field of struct 

F t_access_control_element. 

• You must supply matching passwords in input_dcb- 
>source_file_passwords for FT_FA_READ and 
FT_FA_READ_ATTRI BUTE file actions if the following conditions 
exist. 


• If thefileyou are copying from contains an identity (in 
Ft_access_control_element) that matches the sourcejnitjd AN D 

• If passwords exist for these file actions 

• You must supply matching passwords in input_dcb- 

>dest_file_passwords if thefileyou copying to exists and contains an 
identity (in Ft_access_control_element) that matches the destjnitjd 
and if passwords exist for these file actions. 

• If the file is an FTAM-1, FTAM-3, or INTAP-1 document type, you 
must supply matching passwords for FT_FA_DELETE_FI LE and 
FT_FA_REPLACE. 

• If the file is an FTAM-2 document type, you must supply 
matching passwords for FT_FA_DELETE_FI LE and 

FT FA INSERT. 


Ftfcopyindcb 


struct Ft_fcopy_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_single_file_pw 
enum Ft_delete_overwrite 
struct Ft_concurrency_control 
struct Ft_concurrency_control 


source_init_id; 
source_filestore_pw; 
source_account; 
source_file_passwords; 
dest_init_id; 
dest_filestore_pw; 
dest_account; 
dest_file_passwords; 
create_file_pw; 
overwrite; 
*src_concur_cntl; 
*dest_concur_cntl; 
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F tfcopyou t_dc b 

struct Ft_fcopy_out_dcb { 
Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_attributes 
struct Ft_charging 
struct Ft_diagnostic 

} ; 


size; 

result; 

action_result; 
attributes; 
*charging; 
*diagnostic; 


ftfcopyaetO Parameters 


ftfcopyaetO 

Parameter 

Type 

Description 

source_ascii_ddn 

Optional 1 nput 

Directory distinguished name of the source 
filestore in ASCII; NULL implies local filestore 

source_filename 

M andatory 

1 nput 

Path name of the file you are copying; must be 
in the syntax of the real filestore 

desti nati on_asci i_ddn 

Optional 1 nput 

Directory distinguished name of the destination 
filestore in ASCII; NULL implies local filestore 

dest i n at i on_fi 1 en a me 

Optional 1 nput 

Path name of the file to which you are copying; 
NULL implies source_filename; must be in the 
syntax of the real filestore 

aejabel 

M andatory 

1 nput 

Unique identifier of ftamjnit you want to 
service the request; if pointing to a NULL 
location, the interface uses a currently 
activated ftamjnit or activates and deactivates 
a ftamjnit 


Output 

U nique identifier for ftamjnit that serviced the 
request 

return_event_name 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb-> 
source init id 

Optional 1 nput 

Source login account 
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ft_fcopy_aet() 

Parameter 

Type 

Description 

input_dcb-> 
sou rce_fi 1 estore_pw 

Optional 1 nput 

Login password for thesourcejnitjd account 

input_dcb-> 

source_account 

Optional 1 nput 

Identifies who is responsible for accumulated 
storage charges on source file; H P-UX 
responders accept, but ignore, this value 

input_dcb-> 

sou rce_fi 1 e_passwords 

Optional 1 nput 
(Used only 
with non-H P- 
UX 

responders.) 

Structure containing the passwords for 

FT FA READ and 

FT_FA_READ_ATTRI BUTE. Set 
source_file_passwords only if thefileyou are 
copying from has an identity (in 
Ft_access_control_element) that matches 
sourcejnitjd and if passwords exist for these 
two actions 

input_dcb- 

>dest_init_id 

Optional 1 nput 

Destination login account 

input_dcb-> 

dest_filestore_pw 

Optional 1 nput 

Login password for thedestjnitjd account 

input_dcb-> 

dest_account 

Optional 1 nput 

Identifies who is responsible for accumulated 
storage charges on destination file; HP-UX 
responders accept, but ignore, this value. 

input_dcb-> 
dest_fi 1 e_passwords 

Optional 1 nput 
(Used only 
with non-H P- 
UX 

responders.) 

Structure containing the passwords for the 
actions FT FA DELETE FILE (FTAM-1, 
FTAM-2, FTAM-3, INTAP-1),. Set 
dest_file_passwords only if the file has an 
identity (in Ft_access_control_element) that 
matches destjnitjd and if passwords exist for 
these actions 

input_dcb-> 

create_file_pw 

Optional 1 nput 

Establishes permission to create files in the 
destination filestore 

i nput_dcb- overwrite 

Optional 1 nput 

Determines action taken if the destination file 


exists 
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ft_fcopy_aet() 

Parameter 

Type 

Description 

input_dcb-> 

src_concur_cntl 

Optional 1 nput 
(Used only 
with non-H P- 
UX 

responders.) 

Sets the concurrency control for 
source_filename; compared to conc_access in 
struct Ft_access_control_element if an identity 
field matches the sourcejnitjd 

input_dcb-> 

dest_concur_cntl 

Optional 1 nput 
(Used only 
with non-H P- 
UX 

responders.) 

Sets the concurrency control for 
destination_filename; compared to conc_access 
in struct Ft_access_control_element if an 
identity field matches the destjnitjd 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code (MAP 3.0 
error) and vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

i nout_dcb->attri butes 

Output 

Contains values of the attributes that uniquely 
identify the destination file 

i nout_dcb->chargi ng 

Output 

HP-UX responders do not use charging, though 
it may contain information from other 
responders 

inout_dcb->diagnostic 

Output 

Provides 1 SO-specificerror information 
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ft_fmove_aet() 


#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
Return_code 

ft_fmove_aet(source_ascii_ddn, source_f 
destination_ascii_ddn, dest 
ae_label, return_event_name 

char 

Ft_filename 
char 

Ft_filename 
Ae_label 

Local_event_name 
struct Ft_fmove_in_dcb 
struct Ft fmove out deb 


ilename, 

ination_filename, 

, input_dcb, inout_dcb) 
*source_dirname; 
source_filename; 
*destination_dirname; 
destination_filename; 
*ae_label; 
return_event_name; 
*input_dcb; 

**inout_dcb; 


The ft_fmove_aet() function moves a file from one filestore to another 
(i.e., moves source_filename in the source_dirname filestore to 
destination_filename in the destination_dirnamefilestore). The new file 
contains the source file attributes that are automatically set (e.g., 
filesize). 

• Both ft_fmove_aet() and ft_fmove() are used for moving files. 
However, ft_fmove_aet() sends bot the Cal led AE Title and calling AE 
title to the remote system whileft_fmove() sends only the calling AE 
title. Also, in ft_fmove_aet(), the DDN is passed directly as an ASCI I 
string without conversion while in ft_move(), the DDN has to be 
converted and passed as an Ae_dir_name. 

• If the file you are moving to already exists, the outcome depends on 
how you set input_dcb-overwrite. If input_dcb-overwrite is set to 
FT_RECREATE_FI LE, FTAM copies the source file over the existing 
destination file. If the value is FT_DONT_RECREATE_FI LE, FTAM 
does not copy the source file over the existing file, the function fails, 
and you receive an error. 


NOTE The following points do not apply to H P-UX FTAM responders. H P-UX 

FTAM responders do not use these fields. The information is provided 
here because other implementations may use these fields. 


• If the file has access control elements, and an identity field matches 
thesourcejnitjd, the input_dcb->src_concur_cntl must be a subset 
of the val ues stored i n the conc_access field of struct 
Ft access control element. 
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• If the file has access control elements, and an identity field matches 
thedestjnitjd, the input_dcb->dest_concur_cntl must be a subset of 
the values stored in the conc_access field of struct 

F t_access_control_element. 

• You must supply matching passwords in input_dcb->source_file_ 
passwords for FT_FA_READ, FT_FA_READ_ATTRI BUTE, and 
FT_FA_DELETE_FI LE file actions if the foil owing conditions exist. 

• If thefileyou are moving contains an identity (in 
Ft_access_control_element) that matches the sourcejnitjd AN D 

• If passwords exist for these file actions 

• You must supply matching passwords in input_dcb- 
>dest_file_passwords if thefileyou are moving to exists and contains 
an identity (in Ft_access_control_element) that matches the 
destjnitjd and if passwords exist for these file actions. 

• If the file is an FTAM-1, FTAM-3, or INTAP-1 document type, 
you must supply matching passwords for FT_FA_DELETE_FI LE 
and FT_FA_REPLACE. 

• If the file is an FTAM-2 document type, you must supply 
matching passwords for FT_FA_DELETE_FI LE and 

FT FA INSERT. 


F tfmovei ndcb 


struct Ft_fmove_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_initiator_identity 
Ft_single_file_pw 
Ft_account 

struct Ft_file_passwords 
Ft_single_file_pw 
enum Ft_delete_overwrite 
struct Ft_concurrency_control 
struct Ft_concurrency_control 


source_init_id; 
source_filestore_pw; 
source_account; 
source_file_passwords; 
dest_init_id; 
dest_filestore_pw; 
dest_account; 
dest_file_passwords; 
create_file_pw; 
overwrite; 
*src_concur_cntl; 
*dest_concur_cntl; 
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F tfmoveoutdcb 


struct Ft_fmove_out_dcb { 

Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_attributes 
struct Ft_charging 
struct Ft_diagnostic 

} ; 


size; 

result; 

action_result; 
attributes; 
*charging; 
*diagnostic; 


ft fmove aet() Parameters 


ftfmoveaet() 

Parameter 

Type 

Description 

source_ascii_ddn 

Optional 1 nput 

Directory distinguished name of the source 
filestore in ASCII; NULL implies local filestore 

source_filename 

Mandatory 

Input 

Path name of the file you are moving; must be in 
the syntax of the real filestore 

desti nati on_asci i_dd 
n 

Optional 1 nput 

Directory distinguished name of the destination 
filestore in ASCII; NULL implies local filestore 

destination_filenam 

e 

Optional 1 nput 

Path name of the file to which you are moving; 
NULL implies source_filename; must be in the 
syntax of the real filestore 

aejabel 

Mandatory 

Input 

Uniquely identifier of ftamjnit you want to 
service the request; if pointing to a NULL 
location, the interface uses a currently activated 
ftamjnit or activates and deactivates a ftamjnit 


Output 

Uniquely identifier for ftamjnit that serviced 
the request 

return_event_name 

Mandatory 

Input 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb-> 

source_init_id 

Optional 1 nput 

Source login account 

input_dcb-> 
sou rce_fi 1 estore_pw 

Optional 1 nput 

Login password for thesourcejnitjd account 
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ft_fmove_aet() 

Parameter 

Type 

Description 

input_dcb-> 

source_account 

Optional 1 nput 

Identifies who is responsible for accumulated 
storage charges on source file; HP-UX 
responders accept, but ignore this value 

input_dcb-> 
source file passwor 
ds 

Optional 1 nput 
(Used only 
with non—HP- 
UX 

responders.) 

Structure containing the passwords for 

FT FA READ, FT FA READ ATTRIBUTE, 
and FT_FA_DELETE_FILE. Set 
source_file_passwords only if the file you are 
moving has an identity (in 
Ft_access_control_element) that matches 
sourcejnitjd and if passwords exist for these 
three actions 

input_dcb-> 

destjnitjd 

Optional 1 nput 

Destination login account 

input_dcb-> 

dest_filestore_pw 

Optional 1 nput 

Login password for the destjnitjd account 

input_dcb-> 

dest_account 

Optional 1 nput 

Identifies who is responsible for accumulated 
storage charges on destination file; HP-UX 
responders accept, but ignore, this value 

input_dcb-> 
dest_fi 1 e_passwords 

Optional 1 nput 
(Used only 
with non-H P- 
UX 

responders.) 

Structure containing the passwords for the 
actions FT FA DELETE FILE (FTAM-1, FTAM- 
2, FTAM-3, INTAP-1), FT FA INSERT (FTAM- 
2), and FT_FA_REPLACE (FTAM-1, FTAM-3, 
INTAP-1). Set dest_file_passwords only if thefile 
has an identity (in Ft_access_control_element) 
that matches destjnitjd, and if passwords exist 
for these actions 

input_dcb-> 

create_file_pw 

Optional 1 nput 

Establishes permission to create files in the 
destination filestore 

input_dcb- 

>overwrite 

Optional 1 nput 
(Used only 
with non—HP- 
UX 

responders.) 

Determines action taken if the destination file 
exists 
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input_dcb-> 
src concur cntl 


input_dcb-> 
dest concur cntl 


inout dcb->size 


inout dcb->result 


inout_dcb-> 

action_result 

i nout_dcb- 
>attributes 

i nout_dcb->chargi ng 

i nout_dcb- 
>di agnostic 
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Type 


Description 


Optional I nput 
(Used only 
with non—HP- 
UX 

responders.) 


Sets the concurrency control for source_filename; 
compared to conc_access in struct 
Ft_access_control_element if an identity field 
matches the source init id 


Optional I nput 
(Used only 
with non—HP- 
UX 

responders.) 


Sets the concurrency control for 
destination_filename; compared toconc_access in 
struct Ft_access_control_element if an identity 
field matches the dest init id 


Mandatory Size (in Octets) of the inout_dcb structure and 
input if using data 
inout deb 


Output Poi nter to the struct Api_rc contai ni ng the 

outcome of the operation: result_code (MAP 3.0 
error) and vendor_code (HP-UX—specific error) 

Output Specifies the overall success or failure of the 

request 

Output Contains values of the attributes that uniquely 

identify the destination file 


Output HP-UX responders do not use charging, though 

it may contain information from other responders 


Output 


Provides ISO-specificerror information 
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Reading and Changing Attributes 
(HLCF) 

Useft_frattributes() and ft_frattributes_aet to read file attributes, and 
ft_fcattributes() and ft_fcattributes_aet() to change file attributes by 
making only one call. 

ft_frattributes() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_f rattributes (dirname, filename, ae_label, 

return_event_name, input_dcb, inout_dcb) 
Ae_dir_name dirname; 

Ft_filename filename; 

Ae_label *ae_label; 

Local_event_name return_event_name; 

struct Ft_frattributes_in_dcb *input_dcb; 

struct Ft_frattributes_out_dcb **inout_dcb; 


Useft_frattributes() to read file attributes. Examples of using 
ft_frattributes() are as follows. 

You might want to use ft_frattributes() to determine the creation dates 
when a deleting files older than a specific date. Another example of using 
ft_frattributes() is to know how to set destination file attributes when 
copying files with low level calls. 

• I f the responder supports the conc_access field of struct 
Ft_access_control_element, and the file has access control elements, 
and an identity field matches the initjd, the input_dcb- 
>concurrency_control must be a subset of the values stored in the 
conc_access. H P-UX responders do not support the conc_access field 
of struct Ft_access_control_element. 

• The input_dcb->attribute_names field defaults to indicate all 
attributes in the attribute_groups negotiated. 


226 


Chapters 




Using High Level, Context Free Functions 

Reading and Changing Attributes (HLCF) 


• You must supply matching passwords in input_dcb->file_passwords 
for FT_FA_READ and FT_FA_READ_ATTRI BUTE file actions if the 
following conditions exist. 

• If the file contains an identity (in Ft_access_control_element) that 
matches the initjd AND 

• If passwords exist for these file actions 

• H P-UX responders set storage_account, future_filesize, 
legal_qualifications, and private_use so that the indication no value 
available (0) returns when you invokeft_frattributes(). 

F tfrattr i butesj ndcb 

struct Ft_frattributes_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
struct Ft_file_passwords 
Ft_attribute_names 
Ft_account 

struct Ft_concurrency_control 


init_id; 
filestore_pw; 
file_passwords; 
attribute_names; 
account; 

*concurrency_control; 


F tfrattr i butesoutdcb 


struct Ft_frattributes_out_dcb 

{ 

Uint32 


size; 

struct 

Api_rc 

result; 

enum 

Ft_action_result 

action_resuit 

struct 

Ft_attributes 

attributes; 

struct 

Ft_charging 

*charging; 

struct 

Ft_diagnostic 

*diagnostic; 


}; 
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ft frattributesO Parameters 


ftfrattri butes() 
Parameter 

Type 

Description 

dirname 

Optional 1 nput 

Directory distinguished name of the filestore; 
NULL implies the local filestore 

filename 

M andatory 

1 nput 

Path name of the file that has the attributes you 
are readi ng; must be i n the syntax of the real 
filestore 

aejabel 

M andatory 

1 nput 

Unique identifier for ftamjnit you want to service 
the request; if pointing to a NULL location, the 
interface uses a currently activated ftamjnit or 
activates and deactivates a ftamjnit 


Output 

Unique identifier for ftamjnit that serviced the 
request 

ret u r n_event_n a me 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is 0 (zero) 

input_dcb->init_id 

Optional 1 nput 

Login account 

input_dcb-> 

filestore_pw 

Optional 1 nput 

Login password for initjd 

input_dcb-> 

file_passwords 

Optional 1 nput 

Structure containing the passwords for 
FT_FA_READ and FT_FA_READ_ATTRIBUTE. 
Set file_passwords only if the file has an identity 
(in Ft_access_control_element) that matches 
initjd and if passwords exist for these two actions 

input_dcb-> 

attribute_names 

Optional 1 nput 

Mask that indicates which file attributes to read 

i n put_dcb- >accou nt 

Optional 1 nput 

Identifies who is responsible for accumulated file 
storage charges; HP-UX responders accept, but 
ignore, this value 
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ftfrattri butes() 
Parameter 

Type 

Description 

input_dcb-> 

concurrency_control 

Optional input 
(Used only with 
non—HP-UX 
responders.) 

Sets the concurrency control for filename; 
compared to conc_access in struct 
Ft_access_control_element if an identity field 
matches the initjd 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code (MAP 3.0 
error) and vendor_code (HP-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifiesthe over all su ccess orfailureofthe 
request 

inout_dcb- 
>attributes 

Output 

Contai ns val ues of the attri butes of the file you 
read 

inout_dcb- 
>charging 

Output 

HP-UX responders do not use charging, though it 
may contain information from other responders 

inout_dcb-> 

diagnostic 

Output 

Provides 1 SO-specificerror information 
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ftfcattri butes() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_fcattributes (dirname, filename, ae_label, 

return_event_name, input_dcb, inout_dcb) 
Ae_dir_name dirname; 

Ft_filename filename; 

Ae_label *ae_label; 

Local_event_name return_event_name; 

struct Ft_fcattributes_in_dcb *input_dcb; 

struct Ft_fcattributes_out_dcb **inout_dcb; 


Useft_fcattributes() to change file attributes. For example, you can 
change an attributesuch as access_control to pi ace file access 
restrictions on a specific user. 

• The attribute_groups negotiated dictate the attributes you can 
change. 


Attributes You Can Change 

access_control 

file_avai labi I ity 

filename 

future_filesize* 

legal_qualification* 

private_use* 

storage_account* 


Attributes You Cannot 
Change 

contents_type 

date_ti me_of_attri bute_mod 
date_ti me_of_creati on 
date_ti me_of_modi ficati on 
date_time_of_read filesize 
identity_of_attri bute_mod 
i dent i ty_of_creator 
identity_of_modifier 
identity_of_reader 
permitted_actions 


* H P-UX responders accept, but ignore, these values. 

• I f the responder supports the conc_access field of struct 
Ft_access_control_element, and the file has access control elements, 
and an identity field matches the init_id, the input_dcb- 
>concurrency_control must be a subset of the values stored in the 
conc_access. H P-UX responders do not support the conc_access field 
of struct Ft access control element. 
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• You must supply matching passwords in input_dcb->file_passwords 
for FT_FA_READ and FT_FA_CH ANGE_ATTRI BUTE file actions if 
the following conditions exist. 

• If the file contains an identity (in Ft_access_control_element) that 
matches the initjd AND 

• If passwords exist for these file actions 

Ftfcattri butesi ndcb 

struct Ft_fcattributes_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
struct Ft_file_passwords 
Ft_attribute_names 
struct Ft_attributes 
Ft_account 

struct Ft_concurrency_control 


init_id; 
filestore_pw; 
file_passwords; 
attribute_names; 
attributes; 
account; 

*concurrency_control; 


F tfcattr i butesoutdcb 


struct Ft_fcattributes_out_dcb { 


Uint32 


size; 

struct 

Api_rc 

result; 

enum 

Ft_action_result 

action_resuit 

struct 

Ft_attributes 

attributes; 

struct 

Ft_charging 

*charging; 

struct 

Ft_diagnostic 

*diagnostic; 


}; 


ftfcattributesO Parameters 


ftfcattributesO 

Parameter 

Type 

Description 

dirname 

Optional 1 nput 

Directory distinguished name of the filestore; 
NULL implies the local filestore 

filename 

Mandatory 

1 nput 

Path name of the file that has the attributes you 
are changi ng; must be i n the syntax of the real 
filestore 

aejabel 

Mandatory 

1 nput 

Unique identifier for ftamjnit you want to 
service the request; if pointing to a NULL 


location, the interface uses a currently activated 
ftam init or activates and deactivates a ftam init 
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ftfcattributesO 

Parameter 

Type 

Description 


Output 

Unique identifies theftamjnit that serviced the 
request 

return_event_name 

Mandatory 

1 nput 

1 f the cal 1 is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is 0 (zero) 

input_dcb-> 

attribute_names 

Mandatory 

1 nput 

Mask that indicates which file attributes to 
change 

input_dcb-> 

attributes.values 

Mandatory 

1 nput 

Contai ns val ues you want to change for the 
attributes given in attribute_names 

input_dcb->init_id 

Optional 1 nput 

Login account 

input_dcb-> 

filestore_pw 

Optional 1 nput 

Login password for initjd 

i n put_dcb- >accou nt 

Optional input 

Identifies who is responsible for accumulated file 
storage charges; HP-UX responders accept, but 
ignore, this value 

input_dcb-> 
concu r ren cy_cont r ol 

Optional input 
Used only 
when using 
access control 

Sets the concurrency control for filename; 
compared to conc_access in struct 
Ft_access_control_element if an identity field 
matches the initjd 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code (MAP 3.0 
error) and vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb-> 

attributes 

Output 

Contai ns val ues of the attri butes that changed; 
access_passwords do not return 
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ftfcattributesO 

Parameter 

Type 

Description 

inout_dcb-> 

charging 

Output 

H P-UX responders do not use charging, though it 
may contain information from other responders 

inout_dcb-> 

diagnostic 

Output 

Provides 1 SO-specificerror information 

input_dcb-> 

file_passwords 

Optional 1 nput 

Structure containing the passwords for 

FT FA READ and 

FT_FA_CH ANGE_ATTRI BUTE. Set 
file_passwords only if the file has an identity (in 
Ft_access_control_element) that matches initjd 
and if passwords exist for these two actions 
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ftfrattri butesaetQ 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_frattributes_aet (ascii_ddn, filename, ae_label, 

return_event_name, input_dcb, inout_dcb) 
char *ascii_ddn; 

Ft_filename filename; 

Ae_label *ae_label; 

Local_event_name return_event_name; 

struct Ft_frattributes_in_dcb *input_dcb; 

struct Ft_frattributes_out_dcb **inout_dcb; 


Useft_frattributes_aet() to read file attributes. Examples of using 
ft_frattri butes_aet() are as fol Iows. 

You might want to useft_frattributes_aet() to determine the creation 
dates when a deleting files older than a specific date. Another example of 
using ft_frattributes_aet() is to know how to set destination file 
attributes when copying files with low level calls. 

• Both ft_frattributes_aet() and ft_frattributes() are used for reading 
file attributes. However, ft_frattributes_aet() sends both the Called 
AE Title and calling AE title to the remote system while 
ft_frattributes() sends only the calling AE title. Also, in 
ft_frattributes_aet(), the DDN is passed directly as an ASCI I string 
without any conversion while in ft_frattributes(), the DDN has to be 
converted and passed as an Ae_dir_name. 

• If the responder supports the conc_access field of struct 
Ft_access_control_element, and the file has access control elements, 
and an identity field matches the init_id, the input_dcb- 
>concurrency_control must be a subset of the values stored in the 
conc_access. H P-UX responders do not support the conc_access field 
of struct Ft_access_control_element. 

• The input_dcb->attribute_names field defaults to indicate all 
attributes in the attribute_groups negotiated. 

• You must supply matching passwords in input_dcb->file_passwords 
for FT_FA_READ and FT_FA_READ_ATTRI BUTE file actions if the 
following conditions exist. 

• If the file contains an identity (in Ft_access_control_element) that 
matches the initjd AND 

• If passwords exist for these file actions 
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• H P-UX responders set storage_account, future_filesize, 

legal_qualifications, and private_use so that the indication no value 
available (0) returns when you invoke ft_frattributes_aet(). 


F tfrattr i butesi ndcb 


struct Ft_frattributes_in_dcb { 
Ft_initiator_identity 
Ft_single_file_pw 
struct Ft_file_passwords 
Ft_attribute_names 
Ft_account 

struct Ft_concurrency_control 


init_id; 
filestore_pw; 
file_passwords; 
attribute_names; 
account; 

*concurrency_control; 


F tfrattr i butesoutdcb 


struct Ft_frattributes_out_dcb 

{ 

Uint32 


size; 

struct 

Api_rc 

result; 

enum 

Ft_action_result 

action_resuit 

struct 

Ft_attributes 

attributes; 

struct 

Ft_charging 

*charging; 

struct 

Ft_diagnostic 

*diagnostic; 


}; 


ft_frattributes_aet() Parameters 


ftfrattri butesae 
t() Parameter 

Type 

Description 

ascii_ddn 

Optional Input 

Directory distinguished name of the filestore in 
ASCI 1; NULL implies the local filestore 

filename 

Mandatory 

1 nput 

Path name of the file that has the attributes you 
are reading; must be in the syntax of the real 
filestore 

ae_label 

Mandatory 

1 nput 

Unique identifier for ftamjnit you want to 
service the request; if pointing to a NULL 
location, the interface uses a currently activated 
ftamjnit or activates and deactivates a 
ftamjnit 


Output 

Unique identifier for ftamjnit that serviced the 
request 
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ftfrattri butesae 
t() Parameter 

Type 

Description 

r et u r n_event_n a me 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb->init_id 

Optional 1 nput 

Login account 

input_dcb-> 

filestore_pw 

Optional 1 nput 

Login password for initjd 

input_dcb-> 

file_passwords 

Optional 1 nput 

Structure contai ni ng the passwords for 
FT_FA_READ and FT_FA_READ_ATTRI BUTE. 
Set file_passwords only if the file has an identity 
(in Ft_access_control_element) that matches 
initjd and if passwords exist for these two 
actions 

input_dcb-> 

attribute_names 

Optional 1 nput 

Mask that indicates which file attributes to read 

i nput_dcb->account 

Optional 1 nput 

Identifies who is responsible for accumulated file 
storage charges; HP-UX responders accept, but 
ignore, this value 

input_dcb-> 

concurrency_control 

Optional input 
(Used only with 
non—HP-UX 
responders.) 

Sets the concurrency control for filename; 
compared to conc_access in struct 
Ft_access_control_element if an identity field 
matches the initjd 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code (M AP 3.0 
error) and vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 
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ftfrattri butesae 
t() Parameter 

Type 

Description 

inout_dcb- 
>attri butes 

Output 

Contains values of the attributes of the file you 
read 

i nout_dcb->chargi ng 

Output 

HP-UX responders do not use charging, though 
it may contain information from other 
responders 

inout_dcb-> 

diagnostic 

Output 

Provides 1 SO-specificerror information 
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ftfcattri butes aet() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_fcattributes_aet (ascii_ddn, filename, ae_label, 

return_event_name, input_dcb, inout_dcb) 
char *ascii_ddn; 

Ft_filename filename; 

Ae_label *ae_label; 

Local_event_name return_event_name; 

struct Ft_fcattributes_in_dcb *input_dcb; 

struct Ft_fcattributes_out_dcb **inout_dcb; 


Use ft_fcattributes_aet() to change file attributes. For example, you can 
change an attributesuch as access_control to pi ace file access 
restrictions on a specific user. 

• Both ft_fcattributes_aet() and ft_fcattributes() are used for changing 
file attributes. However, ft_fcattributes_aet() sends both the Called 
AE Titleand calling AE titletothe remote system while 
ft_fcattributes() sends only the calling AE title. Also, in 
ft_fcattributes_aet(), the DDN is passed directly as an ASCI I string 
without any conversion while in ft_fcattributes(), the DDN has to be 
converted and passed as an Ae_dir_name. 

• The attribute_groups negotiated dictatethe attributes you can 
change. 


Attributes You Can Change 

access_control 

file_avai I ability 

filename 

future_filesize* 

legal_qualification* 

private_use* 

storage_account* 


Attributes You Cannot 
Change 

contents_type 

date_ti me_of_attri butejnod 
date_ti me_of_creati on 
date_ti me_of_modi ficati on 
date_ti me_of_read 
filesize 

identity_of_attri bute_mod 
i dent i ty_of_creator 
identity_of_modifier 
identity_of_reader 
permitted_actions 


* H P-UX responders accept, but ignore, these values. 
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• I f the responder supports the conc_access field of struct 
Ft_access_control_element, and the file has access control elements, 
and an identity field matches the initjd, the input_dcb- 
>concurrency_control must be a subset of the values stored in the 
conc_access. H P-UX responders do not support the conc_access field 
of struct Ft_access_control_element. 

• You must supply matching passwords in input_dcb->file_passwords 
for FT_FA_READ and FT_FA_CH ANGE_ATTRI BUTE file actions if 
the following conditions exist. 

• If the file contains an identity (in Ft_access_control_element) that 
matches the initjd AND 

• I f passwords exist for these file acti ons 

Ftfcattri butesj ndcb 

struct Ft_fcattributes_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
struct Ft_file_passwords 
Ft_attribute_names 
struct Ft_attributes 
Ft_account 

struct Ft_concurrency_control 


init_id; 
filestore_pw; 
file_passwords; 
attribute_names; 
attributes; 
account; 

*concurrency_control; 


F tfcattr i butesoutdcb 


struct Ft_fcattributes_out_dcb { 


Uint32 


size; 

struct 

Api_rc 

result; 

enum 

Ft_action_result 

action_resuit 

struct 

Ft_attributes 

attributes; 

struct 

Ft_charging 

*charging; 

struct 

Ft_diagnostic 

*diagnostic; 


}; 
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ft_fcattributes_aet() Parameters 


ftfcattr i butesaet 
() Parameter 

Type 

Description 

ascii_ddn 

Optional 1 nput 

Directory distinguished name of the filestore in 
ASCII; NULL implies the local filestore 

filename 

M andatory 

1 nput 

Path name of the file that has the attributes you 
are changing; must be in the syntax of the real 
filestore 

aejabel 

M andatory 

1 nput 

Uniquely identifier for ftamjnit you want to 
service the request; if pointing to a NULL 
location, the interface uses a currently activated 
ftamjnit or activates and deactivates a ftamjnit 


Output 

Uniquely identifies the ftamj nit that serviced 
the request 

return_event_name 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb-> 

attribute_names 

M andatory 

1 nput 

Mask that indicates which file attributes to 
change 

input_dcb-> 

attributes.values 

M andatory 

1 nput 

Contai ns val ues you want to change for the 
attributes given in attribute_names 

input_dcb->init_id 

Optional 1 nput 

Login account 

input_dcb-> 

filestore_pw 

Optional 1 nput 

Login password for initjd 

i nput_dcb->account 

Optional input 

Identifies who is responsible for accumulated file 
storage charges; HP-UX responders accept, but 
ignore, this value 

input_dcb-> 

concurrency_control 

Optional input 
(Used only 
when using 
access control) 

Sets the concurrency control for filename; 
compared toconc_access in struct 
Ft_access_control_element if an identity field 
matches the i nit_id 
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ftfcattr i butesaet 
() Parameter 

Type 

Description 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code (MAP 3.0 
error) and vendor_code (HP-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb-> 

attributes 

Output 

Contai ns val ues of the attri butes that changed; 
access_passwords do not return 

inout_dcb-> 

charging 

Output 

HP-UX responders do not use charging, though 
it may contain information from other responders 

inout_dcb-> 

diagnostic 

Output 

Provides 1 SO-specificerror information 

input_dcb-> 

file_passwords 

Optional 1 nput 

Structure containing the passwords for 

FT FA READ and 

FT_FA_CHANGE_ATTRI BUTE. Set 
file_passwords only if the file has an identity (in 
Ft_access_control_element) that matches initjd 
and if passwords exist for these two actions 


Chapter 5 


241 



Using High Level, Context Free Functions 

Deleting Files (HLCF) 


Deleting Files (HLCF) 

To delete files, invoke ft_fdelete() or ft_delete_aet(). 


ft_fdelete() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_fdelete (dirname, filename, ae_label, return_event_name, 
input_dcb, inout_dcb) 

Ae_dir_name dirname; 

Ft_filename filename; 

Ae_label *ae_label; 

Local_event_name return_event_name; 

struct Ft_fdelete_in_dcb *input_dcb; 

struct Ft_fdelete_out_dcb **inout_dcb; 

The ft_fdelete() function deletes files from the filestore. Once you delete 
the file, you cannot recover it. 

If the responder supports the conc_access field of struct 
Ft_access_control_element, and the file has access control elements, and 
an identity field matches the initjd, the input_dcb->concurrency_control 
must be a subset of the values stored in the conc_access. H P-UX 
responders do not support the conc_access field of struct 
F t_access_control_el ement. 

F tfdel etei ndcb 

struct Ft_fdelete_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
Ft_single_file_pw 
Ft_account 

struct Ft_concurrency_control 

}; 


init_id; 
filestore_pw; 
de1et e_fi1e_pw; 
account; 

*concurrency_control; 


F tfdel eteoutdcb 


struct Ft_fdelete_out_dcb { 
Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_charging 
struct Ft_diagnostic 

}; 


size; 

result; 

action_resuit; 

^charging; 

^diagnostic; 
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ft_fdelete() Parameters 


ft fdeleteO 
Parameter 

Type 

Description 

dirname 

Optional 1 nput 

Directory distinguished name of the filestore; 
NULL implies the local filestore 

filename 

Mandatory 

1 nput 

Path name of the file you are deleting; must be in 
the syntax of the real filestore 

aejabel 

Mandatory 

1 nput 

Unique identifier for ftamjnit you want to service 
the request; if pointing to a NULL location, the 
interface uses a currently activated ftamjnit or 
activates and deactivates a ftamjnit 


Output 

Unique identifier for ftamjnit that serviced the 
request 

return_event_na 

me 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, thevalueis 
0 (zero) 

input_dcb- 

>init_id 

Optional 1 nput 

Login account 

input_dcb-> 

filestore_pw 

Optional 1 nput 

Login password for initjd 

input_dcb-> 

delete_file_pw 

Optional 1 nput 

Establishes permission to delete files from the 
filestore; HP-UX responders accept, but ignore, 
this value 

input_dcb- 

>account 

Optional 1 nput 

Identifies who is responsible for accumulated file 
storage charges; HP-UX responders accept, but 
ignore, this value 

input_dcb-> 
concurrency cont 
rol 

Optional input 
(Used only with 
non—HP-UX 
responders.) 

Sets the concurrency control for filename; 
compared to conc_access in struct 
Ft_access_control_element if an identity field 
matches the i nit_id 
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ft_fdelete() 

Parameter 

Type 

Description 

inout_dcb->5ize 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the outcome 
of the operation: result_code (M AP 3.0error)and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb- 

>charging 

Output 

HP-UX responders do not use charging, though it 
may contain information from other responders 

inout_dcb-> 

diagnostic 

Output 

Provides 1 SO-specificerror information 
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ft_fdelete_aet() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_fdelete_aet (ascii_ddn, filename, ae_label, 

return_event_name, input_dcb, inout_dcb) 
char *ascii_ddn; 

Ft_filename filename; 

Ae_label *ae_label; 

Local_event_name return_event_name; 

struct Ft_fdelete_in_dcb *input_dcb; 

struct Ft_fdelete_out_dcb **inout_dcb; 

The ft_fdelete_aet() function deletes files from the filestore. Once you 
delete the file, you cannot recover it. 

If the responder supports the conc_access field of struct 
Ft_access_control_element, and the file has access control elements, and 
an identity field matches the initjd, the input_dcb->concurrency_control 
must be a subset of the values stored in the conc_access. H P-UX 
responders do not support the conc_access field of struct 
F t_access_control_el ement. 

Both ft_fdelete_aet() and ft_fdelete() are used for deleting files. However, 
ft_fdelete_aet() sends both theCalled AE Titleand calling AE titletothe 
remote system while ft_fdelete() sends only the cal ling AE title. Also, in 
ft_fdelete_aet(), the DDN is passed directly as an ASCI I string without 
any conversion while in ft_fdelete(), the DDN has to be converted and 
passed as an Ae_dir_name. 

F tfdel etei ndcb 

struct Ft_fdelete_in_dcb { 

Ft_initiator_identity 
Ft_single_file_pw 
Ft_single_file_pw 
Ft_account 

struct Ft_concurrency_control 

}; 

F tfdel eteoutdcb 

struct Ft_fdelete_out_dcb { 

Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_charging 
struct Ft_diagnostic 

}; 


size; 

result; 

action_resuit; 

^charging; 

^diagnostic; 


init_id; 
filestore_pw; 
de1et e_fi1e_pw; 
account; 

*concurrency_control; 
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ftfdeleteaet() Parameters 


ftfdeleteaetO 

Parameter 

Type 

Description 

ascii _ddn 

Optional 1 nput 

Directory distinguished name of the filestore in 
ASCI 1; NULL implies the local filestore 

filename 

Mandatory 

1 nput 

Path name of the file you are deleting; must be in 
the syntax of the real filestore 

aejabel 

Mandatory 

1 nput 

Unique identifier for ftamjnit you want to service 
the request; if pointing to a NULL location, the 
interface uses a currently activated ftamjnit or 
activates and deactivates a ftamjnit 


Output 

Unique identifier for ftamjnit that serviced the 
request 

return_event_na 

me 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, thevalueis 
0 (zero) 

input_dcb- 

>init_id 

Optional 1 nput 

Login account 

input_dcb-> 

filestore_pw 

Optional 1 nput 

Login password for initjd 

input_dcb-> 

delete_file_pw 

Optional 1 nput 

Establishes permission to delete files from the 
filestore; HP-UX responders accept, but ignore, 
this value 

input_dcb- 

>account 

Optional 1 nput 

Identifies who is responsible for accumulated file 
storage charges; HP-UX responders accept, but 
ignore, this value 

input_dcb-> 
concurrency cont 
rol 

Optional input 
(Used only with 
non—HP-UX 
responders.) 

Sets the concurrency control for sourceJhlename; 
compared to conc_access in struct 
Ft_access_control_element if an identity field 
matches the sourcejnitjd 
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ftfdeleteaet() 

Parameter 

Type 

Description 

inout_dcb->5ize 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the outcome 
of the operation: result_code (M AP 3.0error)and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the over a 11 success or fai 1 ure of the 
request 

inout_dcb- 

>charging 

Output 

HP-UX responders do not use charging, though it 
may contain information from other responders 

inout_dcb-> 

diagnostic 

Output 

Provides 1 SO-specificerror information 
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Managing HP FTAM/9000 Connections 


To use context sensitive FTAM operations, you must first activate an 
application entity (AE) and then establish a connection. The AE that you 
activate is an FTAM initiator (ftamjnit). Use connection management 
functions to control activations and connections. Refer to the "Example 
Programs" chapter for model programs using the connection 
management functions. 
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C hapter Overview 

Thischapter describes the following functions in the order listed. 


Task to Perform 

Function Used 
to Perform the 
Task 

Starti ng and Stoppi ng 
Application Entities 

ft_aeactivation() 


ft_aedeactivation() 

Establishing and 
Removing 

Connections 

ft_connect() 


ft_rrequest() 


ft_aereset() 

Aborting Connection 
Requests 

ft_abort() 


ftjreceive() 


Description 

Activate ftamj nit 
Deactivate ftamj nit 

Establish connection from ftamjnit to the 
responder 

Release connection from the responder 

Abort all active connections for a ftamjnit, 
and then reset ftamjnit 

Abort one connection at any time 

Determine who aborted the call and receive 
abort indication information 
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Connection Establishment Process 

A typical connection establish and release routine (algorithm) is as 
follows. You do not have an option regarding the sequence of these 
events, with the exception of step 4. (Refer to Figure 6-1.) 

1. Activateftamjnit (usingft_aeactivation()). 

2. Establish the connection (using ft_connect()) between ftamjnit and 
the responder. Note that during the life of the ftamj nit, you can 
establish and release connections arbitrarily. 

3. Use FTAM operations as needed. 

4. Release the connection (using ft_rrequest()). Alternatively, you can 
use one of the fol I owi ng functi ons: 

• ft_aereset() to release all active connections for that ftamj nit. 

• ft_abort() used at any time aborts a connection. 

5. Deactivate ftamj nit (using ft_aedeactivation()). 


NOTE This chapter does not explain the parameter structures. For detailed 

structure information (parameter settings), refer tothe "FTAM Data 
Structures" chapter. 
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Figure 6-1 Connection Establishment Process 




ft_aeactivation() 

f User \ 

1 Program) 



^ftamjnitj 

(^ftam^esp) 

ft_connect() 

f User \ 
l Program) 

ftam_resp(A) forks another process 

New ftam_resp(B) services the request.» 

ftam_resp (A) waits for other connections 


^tamjnitj 

r®\ 

1 ftam_respj-> 1 ftam_resp) 

ft_rrequest() 

f User \ 
l Program) 



^ftamjnitj 

^ftam^resp) 

ft_deactivation() 

f User \ 

1 Program) 

^ftam^esp) 


Chapter 6 


253 








Managing HP FTAM/9000 Connections 

Starting and Stopping Application Entities 


Starting and Stopping Application 
Entities 

Useft_aeactivation() and ft_aedeactivation() to respectively start and 
stop ftamjnit. 

ft_aeactivation() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_aeactivation(my_dir_name, return_event_name, input_dcb, 
inout_dcb, ae_label) 

Ae_dir_name my_dir_name; 

Local_event_name return_event_name; 

struct Ft_aeactivate_in_dcb *input_dcb; 
struct Ft_output **inout_dcb; 

Ae_label *ae_label; 


You must invoke ft_aeactivation() before establishing a connection. By 
passing my_dir_name (the local ftamjnit directory distinguished name) 
as input, the interface returns the aejabel of the activated ftamjnit. 
Note, directory distinguished names are in the I nitial Configuration 
Store (ICS); they are defined during system configuration and when 
nodes are added to the network. 

Using my_dir_name requires that you set up Ae_dir_dn. You can do so 
manually (as explained in the "FTAM Data Structures" chapter) or you 
can call the convert_ddn utility. This utility eases the setting of 
Ae_dir_dn by automatically setting it and its sub-structures for you. The 
source for convert_ddn is in /opt/ftam/demos/cnvrt_addr.c. (For 
instructions, read the on-line README document in this directory.) The 
"Example Programs" chapter also contains the source for convert_ddn. 

Ftaeactivationi ndcb 

struct Ft_aeactivate_in_dcb { 
struct Octet_string 
enum Ae_title_option 
Ae_title 

}; 


authentication; 

my_ae_title_option; 

*my_ae_title; 
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Ftoutput 

struct Ft_output { 

Uint32 size; 

struct Api_rc result; 

}; 

ft aeactivationO Parameters 


ftaeacti vati on () 
Parameter 

Type 

Description 

my_di r_name 

M andatory 

1 nput 

Directory distinguished name identifying the AE 
(ftamjnit) you want to activate 

return_event_nam 

e 

M andatory 

1 nput 

1 f the cal 1 is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value is 
0 (zero) 

input_dcb-> 

authentication 

Optional 1 nput 

ftamjnit accepts, but ignores, this value 

input_dcb-> 
my_a e_t i 11 e_opt i on 

Optional 1 nput 

Dictates the interpretation of my_ae_title If it 
indicates Dir_dist_name_option, my_dir_name 
must be usable as an address for the local ftamjnit 
Default is No_value_option 

input_dcb-> 

my_ae_title 

Optional 1 nput 

Optional ae_titlesent to the peer AE, which can be 
either a directory distinguished name or an 
objectjd; determined by how you set 
my_ae_t i 11 e_opt i on 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the outcome 
of the operation: result_code and vendor_code 
(H P-UX—specific error) 

aejabel 

Output 

Uniquely identifies the A E (ftamj nit) that serviced 
the request 
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ftaedeacti vati on() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_aedeactivation(ae_label, return_event_name, inout_dcb) 
Ae_label *ae_label; 

Local_event_name return_event_name; 

struct Ft_output **inout_dcb; 


Useft_aedeactivation() to deactivate the AE (ftamjnit) servicing the 
request. 

Ftoutput 

struct Ft_output { 

Uint32 

struct Api_rc 

}; 


size; 

result; 


ft_aedeactivation() Parameters 


ftaedeactivati 
on() Parameter 

Type 

Description 

ae_label 

Mandatory 

1 nput 

Uniquely identifies the AE (ftamjnit) you want to 
deactivate 

return_event_na 

me 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value is 
0 (zero) 

inout_dcb->5ize 

Mandatory 
input if using 
i nout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the outcome 
of the operation: result_code and vendor_code 
(HP-UX—specific error) 
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E stabl i sh i ng and Removi ng C on necti ons 

Usetheft_connect(), ft_rrequest(), and ft_aereset() functions to connect, 
release connections, and reset connections in an orderly manner. 

ft_connect() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_connect(ae_label, return_event_name, called_dir_name, 
input_dcb, inout_dcb, connection_id) 

Ae_label ae_label; 

Local_event_name return_event_name; 

Ae_dir_name called_dir_name; 

struct Ft_connect_in_dcb *input_dcb; 

struct Ft_connect_out_dcb **inout_dcb; 

Connection_id *connection_id; 


Useft_connect() to establish a connection from ftamjnit to an FTAM 
responder. Remember, you must first invoke ft_aeactivation() to start 
ftamjnit. 

You will use the returned connectionjd on all subsequent, context 
sensitive FTAM calls to uniquely identify the connection to the desired 
filestore. 

• When invoking ft_connect(), the document types, functional_units, 
and service_classes are negotiated with the responder. When the 
request is complete, check these fields in the inout_dcb to see if the 
responder accepted these val ues, accepted a subset of these val ues, or 
rejected these values. 

• You must set either the input_dcb->called_presentation_address or 
thecalled_dir_name. If you set both fields, 

input_dcb->called_presentation_address takes precedence. Refer to 
the "FTAM Data Structures" chapter to set either of these 
parameters. 

Specifying these fields requires that you set up the appropriate 
structures. You can do so manually (as explained in the "FTAM Data 
Structures" chapter) or you can call one of the foil owing utilities. 

• To have the system set the P_address, cal I convert_paddr; the source 
is in /opt/ftam/demos/cnvrt_addr.c. 
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• To have the system set the Ae_di r_name, cal I convert_ddn; the source 
is in /opt/ftam/demos/cnvrt_addr.c. 

For instructions on using these utilities, read the on-line README 
document in /opt/ftam/demos/cnvrt_addr.c. The "Example Programs" 
chapter also contains the source for convert_paddr and convert_ddn. 

• For FIP-UX responders, the login name 
(connectjnjnfo.initiatorjdentity) must exist on the remote node, 
andthefile_store_pw must bethat user's password. Other responders 
may or may not have similar expectations. 

• The inout_dcb structure contains the responder's reply to the 
requested connection parameters. 


F tcon necti ndcb 


struct Ft_connect_in_dcb { 
struct P_address 
enum Ae_title_option 
Ae_title 
Uint32 
Uint32 
Uint8 
Uint32 
Uint32 

struct Object_id 

struct Ft_connect_req_info 


called_presentation_address; 

called_ae_title_option; 

*called_ae_title; 

called_ae_invoke_id; 

called_ap_invoke_id; 

number_of_retry; 

delay_between_retry; 

connection_resource_wait_timer 

context_name; 

connect_in_info; 


struct Ft_connect_req_info { 
Ft_service_class 
Ft_functional_units 
Ft_attribute_groups 
enum Ft_qos 

struct Ft_contents_type_ 
Ft_initiator_identity 
Ft_account 
Ft_single_file_pw 


service_class; 
functional_units; 
attribute_groups; 
quality_of_service; 
lement *contents_type_list; 

initiator_identity; 
account; 
f ile_store_pw; 
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F tcon nectoutdcb 


struct Ft_connect_out_dcb { 

Uint32 

struct Api_rc 
struct P_address 
responding_presentation_address; 

Ae 

Uint32 

Uint32 

struct Object_id 

struct Ft_connect_cnf_info 

}; 


size; 

result; 


responding_ae; 
responding_ae_invoke_id; 
responding_ap_invoke_id; 
context_name; 
*connect_out_info; 


struct Ft_connect_cnf_info { 
enum Ft_state_result 
enum Ft_action_result 
Ft_service_class 
Ft_functional_units 
Ft_attribute_groups 
enum Ft_qos 

struct Ft_contents_type_element 
struct Ft_diagnostic 
enum Ft_acse_result 
struct Ft_acse_diagnostic 

}; 


state_result; 

action_resuit; 

service_class; 

functional_units; 

attribute_groups; 

quality_of_service; 

contents_type_list; 

*diagnostic; 

acse_result; 

acse_diag; 


ft_connect() Parameters 


ft_connect() 

Parameter 


Type 


Description 


ae label 


return event name 


called dir name 


Mandatory I n put Uniquely identifies the AE (ftamjnit) you 
want to service the request 

Mandatory I n put I f the cal I is asynchronous, uniquely 

identifies the function call; if the call is 
synchronous, the value is 0 (zero) 


Mandatory I nput Directory distinguished name identifying 
if nocalled_ the responder to which you want to 

presentation_addr connect 
ess given; 
otherwise, 

Optional Input 
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ft_connect() 

Parameter 

Type 

Description 

input_dcb->called_ 
presentati on_address 

Mandatory 1 nput 
if no 

called_dir_name 
given; otherwise, 
Optional 1 nput 

Contains addressing information for the 
remote responder 

input_dcb-> 

ca 11 ed_ae_t i 11 e_opt i on 

Optional 1 nput 

Dictates the interpretation of 
called_ae_title If it indicates 

Dir_dist_name_option, cal 1 ed_di r_name 
must be usable as an address for the 
remote responder Default is 
No_value_option 

input_dcb-> 

called_ae_title 

Optional 1 nput 

Optional ae_titlesent to the peer AE Can 
be either a directory distinguished name 
or an objectjd Determined by how you set 
ca 11 ed_a e_t i 11 e_opt i on 

input_dcb-> 

cal 1 ed_ae_i nvoke_i d 

Optional 1 nput 

H P-UX responders accept, but ignore, this 
undefined value; default setting is 
NO_VALUE 

input_dcb-> 

cal 1 ed_ap_i nvokej d 

Optional 1 nput 

H P-UX responders accept, but ignore, this 
undefined value; default setting is 
NO_VALUE 

input_dcb-> 

number_of_retry 

Optional 1 nput 

N umber of times (in tenths of seconds) to 
retry the connection attempt; default is 
zero 

input_dcb-> 

del ay_between_retry 

Optional 1 nput 

Amount of time (in tenths of seconds) to 
wait between retrying to establish the 
connection; default is zero 

i nput_dcb->connection_ 
resource_wait_ti mer 

Optional 1 nput 

M axi mum ti me (i n tenths of seconds) to 
wait for an available association resource; 
default is zero 

input_dcb-> 

context_name 

Mandatory 1 nput 

Association Control Service Element 
(ACSE) context name; you must set this 


value to 1 0 8571 1 1 
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ft_connect() 

Parameter 

Type 

Description 

i nput_dcb->connect_ 
i n_i nfo.servi ce_cl ass 

Mandatory 1 nput 

Determines whether you transfer, access, 
or manage a file on this connection 

i nput_dcb->connect_ 
i n_i nfo.functi onal_units 

Mandatory 1 nput 

Determines which functions are available 
per connection 

i nput_dcb->connect_ 
i n_i nfo.attri bute_groups 

Mandatory 1 nput 

Specifies the set of attributes (level of 
support) avail able on the association 

i n put_dcb- >con nect_i n_ 
i nfo.qual i ty_of_servi ce 

Optional 1 nput 

Determines the level of available recovery; 
FTAM does not automatically attempt 
recovery 

i n put_dcb- >con nect_i n_ 
i nfo.contents_type_l i st 

Optional Input 

Specifies the allowable document type for 
the connection 

i n put_dcb- >con nect_i n_ 
i nf o. i n i t i atorj dent i ty 

Optional Input 

Login account name, which must exist on 
the node to which you are connecting 

i nput_dcb->connect_ 
in_info. account 

Optional 1 nput 

H P-UX responders accept, but ignore, this 
value 

i n put_dcb->con nect_i n_ 
i nfo.fi le_st or e_pw 

Optional Input 

Login password for the initiatorjdentity 

inout_dcb->size 

Mandatory input 
if using inout_dcb 

Size (in Octets) of the inout_dcb structure 
and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

i nout_dcb->respondi ng_ 
presentati on_address 

Output 

presentati on_address returned by the 
responder 

inout_dcb-> 

responding_ae 

Output 

ae_title returned by the responder 

i nout_dcb->respondi ng_ 
ae_invoke_id 

Output 

HP-UX responders accept, but ignore this 
undefined value 

i nout_dcb->respondi ng_ 
ap_invoke_id 

Output 

HP-UX responders accept, but ignore this 
undefined value 
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ft_connect() 

Parameter 

Type 

Description 

inout_dcb-> 

context_name 

Output 

context_name accepted by the responder 

i nout_dcb->connect_ 
out_i nfo->state_resu It 

Output 

1 ndi cates whether the request moved 
through regimes; if a failure returns, you 
will also receive an action result of 
FT_AR_PERM ANENT_ERROR 

i nout_dcb->connect_ 
out_info->action_result 

Output 

Specifies the overal 1 success or fai 1 ure of 
the request 

i nout_dcb->connect_ 
out_i nfo >ser vi ce_cl ass 

Output 

H ighest service_class the responder 
supports 

inout_dcb-> 
connect_out_i nfo-> 
functional_unit 

Output 

fundional_units accepted by the 
responder 

inout_dcb-> 
connect_out_i nfo-> 
attribute_groups 

Output 

attribute_groups accepted by the 
responder 

inout_dcb-> 
connect_out_i nfo-> 
quality_of_service 

Output 

Level of available recovery; FTAM does 
not automatically attempt recovery 

inout_dcb-> 
connect_out_i nfo-> 
contents_type_list 

Output 

contents_types (document types) accepted 
by the responder 

i nout_dcb->connect_ 
out_info->di agnostic 

Output 

Provides 1 SO-specificerror information 

i nout_dcb->connect_ 
out_i nfo->acse_resu It 

Output 

1 ndi cates overall result of ACSE 
processing 

i nout_dcb-> 
connect_out_i nfo-> 
acse_di agnostic 

Output 

Provides Association Control Service 
Element (ACSE) diagnostic information 

connectionjd 

Output 

Uniquely identifies theconnedion to the 
filestore; use this connedionjd as input to 
subsequent cal Is to identify the connedi on 
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ft_rrequest() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_rrequest (connection_id, return_event_name, input_dcb, 
inout_dcb) 

Connection_id connection_id; 

Local_event_name return_event_name; 

struct Ft_relreq_in_dcb *input_dcb; 

struct Ft_relreq_out_dcb **inout_dcb; 

Useft_rrequest to release a specific connection; afterwards, the 
connection no longer exists; you must establish a new connection (using 
ft_connect()). 

Theft_rrequest() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

Ftrelreqindcb 

struct Ft_relreq_in_dcb { 

struct Ft_release_req_info release_in_info; 

In¬ 
struct Ft_release_req_info { 

char *ft_rel_info; 

}; 

F trel reqoutdcb 

struct Ft_relreq_out_dcb { 

Uint32 

struct Api_rc 
struct Ft_release_cnf_info 
In¬ 
struct Ft_release_cnf_info { 

struct Ft_charging ^charging; 

} ; 


size; 
result; 
*output_info; 
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ft_rrequest() 

Parameter 

Type 

Description 

connection_id 

Mandatory 

Input 

Uniquely identifies the connection you want to 
release 

return_event_na 

me 

Mandatory 

Input 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, thevalueis 
0 (zero) 

input_dcb 

Optional 1 nput 

Contains no information; pass a NULL pointer 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the outcome 
of the operation: result_code and vendor_code 
(H P-U X—specific error) 

inout_dcb->outpu 
t_ info-charging 

Output 

HP-UX responders do not use charging, though it 
may contain information from other responders 


ft_aereset() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 
Return_code 

ft_aereset(ae_label, return_event_name, inout_dcb) 
Ae_label ae_label; 

Local_event_name return_event_name; 

struct Ft_output **inout_dcb; 


Useft_aereset() to abort all open connections and return ftamjnit to its 
initial state. 

Ftoutput 

struct Ft_output { 

Uint32 

struct Api_rc 

}; 


size; 
result; 
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ft_aereset() 

Parameter 

aejabel 

return_event_na 

me 

inout_dcb->5ize 

inout dcb->result 


ft_aereset() Parameters 


Type 


Description 


Mandatory 
I nput 

Mandatory 
I nput 


Mandatory 
input if using 
i nout_dcb 

Output 


Uniquely identifies the AE (ftamjnit) you want to 
reset 

If the cal I is asynchronous, uniquely identifies the 
function call; if the call is synchronous, thevalueis 
0 (zero) 

Size (in Octets) of the inout_dcb structure and data 


Poi nter to the struct Api_rc contai ni ng the outcome 
of the operation: result_code and vendor_code 
(H P-U X— specific error) 
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Aborting Connections 

Use ft_abort() to abort a connection and ftJreceiveQ to determine why 
you received an abort indication. 


NOTE 


ft_abort() 


#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_abort(connection_id, return_event_name, input_dcb, 
inout_dcb) 

Connection_id connection_id; 

Local_event_name return_event_name; 

struct Ft_abort_in_dcb *input_dcb; 

struct Ft_output **inout_dcb; 


Useft_abort()toabruptlyterminateaconnection at any time (i.e., in any 
regi me). 


If you abort while writing data, you could lose any or all data written 
during that transfer; you will not, however, lose the source file. 


F taborti ndcb 


struct 

} ; 


Ft_abort_in_dcb { 

struct Ft_abort_req_info info; 


struct Ft_abort_req_info { 

enum Ft_action_result 
struct Ft_diagnostic 

} ; 


action_result; 
*diagnostic; 


Ftoutput 

struct Ft_output { 

Uint32 size; 

struct Api_rc result; 

}; 
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ft_abort() Parameters 


ft_abort() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 

1 nput 

U niquely identifies the specific filestore connection 
to abort 

return_event_na 

me 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, thevalueis 
0 (zero) 

input_dcb-> 

info.action_result 

Mandatory 

1 nput 

Conveys the reason for the abort 

input_dcb-> 
info.di agnostic 

Optional 1 nput 

1 SO-specificerror information; HP-UX responders 
accept, but ignore, this value 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the outcome 
of the operation: result_code and vendor_code 
(H P-UX—specific error) 


ft_ireceive() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_ireceive(connection_id, return_event_name, inout_dcb, 
indication_name) 

Connection_id connection_id; 

Local_event_name return_event_name; 

struct Ft_indication_out_dcb *inout_dcb; 

Uint32 *indication_name; 


If you receive the FTE003_ABORT_IND_RCVD error, call ft_ireceive() 

• to determine whether the abort was caused by the system (initiator, 
responder, or network) or by a user, and 

• to receive diagnostics. 
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The information regarding the type of abort returns in the 
indication_name parameter and may be useful for troubleshooting 
purposes. 

All diagnostics associated with the abort are returned in the inout_dcb. 

Ftindicationoutdcb 

struct Ft_indication_out_dcb { 

Uint32 

struct Api_rc 

union Ft_specific_indication_info 

}; 


union Ft_specific_indication_info { 
struct Ft_aabort_ind_info 
struct Ft_pabort_ind_info 

In¬ 


struct Ft_aabort_ind_info { 
enum Ft_action_result 
struct Ft_diagnostic 

In¬ 


struct Ft_pabort_ind_info { 

enum Ft_action_result action_result; 

struct Ft_diagnostic ^diagnostic; 

} ; 


action_resuit; 
^diagnostic; 


aabort_info; 
pabort_info; 


size; 

result; 

info; 
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ft_ireceive() Parameters 


ft_ireceive() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 1 nput 

Uniquely identifies the aborted connection 

return_event_name 

Mandatory 1 nput 

If the call is asynchronous, uniquely 
identifies the function call; if the call is 
synchronous, the value is 0 (zero) 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure 
and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb->info. 

aabort_info.action_result 

Output 

Specifies that an application caused the 
abort Specifies the overall successor 
failure of the request 

inout_dcb->info. 
aabortj nfo.di agnostic 

Output 

Specifies that an application caused the 
abort; provides 1 SO-specific error 
information 

inout_dcb->info. 

pabort_info.action_result 

Output 

Specifies that the system caused the abort 
Specifies the overall success or failure of 
the request 

inout_dcb->info. 
pabort_i nfo.di agnostic 

Output 

Specifies that the system caused the abort; 
provides 1 SO-specific error information 

indication_name 

Output 

Specifies if the abort was a system 
(FT_PABORT_l ND) or application 
(FT_AABORT_l ND) abort; dictates which 
union Ft_specific_indication_infocontains 
the output information 
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After establishing connections, you can manage and access FTAM files. 
Refer to the "E xampl e P rograms" chapter for model programs usi ng 
these functions. 
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C hapter Overview 

Thischapter describes the following functions in the order listed. 


Task to Perform 

Function Used to 
Perform the Task 

Description 

Gaining Access to Files 

ft_create() 

Create files 


ft_select() 

Select files 


ft_open() 

Open files (LLCS) 


ft_close() 

Close files (LLCS) 


ft_delete() 

Delete files (LLCS) 


ft_deselect() 

Deselect files 

Opening and Closing Files 

ft_fopen() 

Select or create, and then open 
files (HLCS) 


ft_fclose() 

Close and then deselect or 
delete files (FHLCS) 

Reading and Changing 
Attributes 

ft_rattributes() 

Read attributes (LLCS) 


ft_cattributes() 

Change attributes (LLCS) 

Locating and Erasing FTAM 
Files 

ft_locate<) 

Locate FADUs within files 


ft_erase() 

Erase files 

Grouping FTAM Functions 

ft_bgroup() 

Begin a group of FTAM calls 


ft_egroup() 

End a group of FTAM calls 


NOTE This chapter does not explain the parameter structures. For detailed 

structure information (parameter settings), refer tothe "FTAM Data 
Structures" chapter. 
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Gaining Access to FTAM Files 

After establishing a connection, either select (ft_select()) or create 
(ft_create()) a file for further manipulation. You must always select a file 
before opening it (ft_open()), though the selection automatically occurs if 
you create the file. 

After performing FTAM operations, close (ft_close()) the file and then 
deselect (ft_deselect()) or delete (ft_delete()) it. The file remains intact if 
you deselect it; if you delete the file, it no longer exists. 


ft_create() 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return code 

ft_create (connection_id, filename, contents_type, 

requested_access, file_status, return_event_name, 
input_dcb, inout_dcb) 


Connection_id 
Ft_filename 

struct Ft_contents_type 
Ft_file_actions 
enum Ft_file_status 
Local_event_name 
struct Ft_create_in_dcb 
struct Ft_create_out_dcb 


connection_id; 
filename; 
contents_type; 
requested_access; 
file_status; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Use ft_create() to create a new file. I f successful, ft_create() 

automatically selects the file. 

• I nvokeft_create() in the FTAM regimetomovetotheFileSelection 
regi me. 

• During ft_connect(), you must negotiate the FT_FU_LTD_M GMT 
functional_units to useft_create(). 

• If the file already exists, thefile_status parameter determines 
whether a new file is created or the request fails. (Refer to the 
"Ft_file_status" section in the "FTAM Data Structures" chapter for 
options on setting this field.) 
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• The subset of the input_dcb->attributes.mask field (of type struct 
Ft_attributes) that is valid for ft_create() is as follows. 


FT_AN_ACCESS_CONTROL 
FT_AN_FILE_AVAI LABILITY 
FT_AN_FUTURE_FI LESIZE 
FT AN ID OF CREATOR 


FT_AN_LEGAL_QUAL 
FT_AN_PERM ITTED_ACTI ON 
S FT_AN_PRI VATE_USE 
FT AN STORAGE ACCOUNT 


• If you do not specify permitted_actions, FTAM uses the 
requested_access values for the permitted_actions values. 

• FTAM uses the exposed parameters filename and contents_type and 
does not use input_dcb->attributes.values.filename and input_dcb- 
>attri butes.val ues.contents_type. 

Ftcreateindcb 

struct Ft_create_in_dcb { 
struct Ft_attributes 
struct Ft_concurrency_control 
Ft_sing1e_fi1e_pw 
struct Ft_file_passwords 
Ft_account 


F tcreateoutdcb 

struct Ft_create_out_dcb { 


Uint32 


size; 

struct 

Api_rc 

result; 

enum 

Ft_state_result 

state_result; 

enum 

Ft_action_result 

action_resuit 

struct 

Ft_attributes 

attributes; 

struct 

Ft_diagnostic 

*diagnostic; 


attributes; 
*concurrency_control; 
create_file_pw; 
file_passwords; 
account; 
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ft_create() Parameters 


ft_create() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

filename 

Mandatory 

1 nput 

Path name of the file you arecreating; must be in 
the syntax of the real filestore 

contents_type 

Mandatory 

1 nput 

Specifies the document type of the newly created 
file 

requested_access 

Mandatory 

1 nput 

Specifies the actions you want available for the 
connection (during the File Selection regime and 
those regimes nested within it) 

file_status 

Mandatory 

1 nput 

Determines the action to take if the file already 
exists 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is 0 (zero) 

input_dcb- 

>attributes 

Optional 1 nput 

Uniquely identifies thefileyou arecreating; do 
not use input_dcb->attributes.filename and 
i nput_dcb->attri butes.contents_type 

input_dcb-> 
concu r ren cy_cont r ol 

Optional 1 nput 

File access locks required on the actions specified 
in requested_access 

input_dcb-> 

create_file_pw 

Optional 1 nput 

Establishes permission to create files in the 
current filestore; FHP-UX responders ignore this 
value 

input_dcb-> 

file_passwords 

Optional 1 nput 

Passwords associated with the actions specified by 
request ed_access 

i n put_dcb->accou nt 

Optional 1 nput 

H P-UX responders accept, but ignore, this value 

inout_dcb->size 

Mandatory 
input if using 
inout deb 

Size (in Octets) of the inout_dcb structure and 
data 
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ft_create() 

Parameter 

inout dcb->result 


inout_dcb-> 
state result 


inout_dcb-> 

action_result 

i nout_dcb- 
>attributes 


i nout_dcb- 
>di agnostic 


Type 


Description 


Output 


Output 


Output 


Output 


Output 


Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

I ndicates whether the request moved from the 
FTAM regime to the File Selection regime; if a 
failure returns, you will also receive an 
action_result of FT_AR_PERMANENT_ERROR 

Specifies the overall success or failure of the 
request 

Contai ns val ues of the attri butes of the file you 
created (those attributes accepted by the 
responder) 

Provides I SO-specific error information 


ft_select() 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_select (connection_id, filename 
return_event_name 


Connection_id 
Ft_filename 
Ft_file_actions 
Local_event_name 
struct Ft_select_in_dcb 
struct Ft_select_out_dcb 


requested_access, 
input_dcb, inout_dcb) 

connection_id; 
filename; 
requested_access; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_select() to choose an existing file for file management or access 
(e.g., reading attributes, opening a file). You select a file based only on its 
filename. 

• I nvokeft_select() in the FTAM regime to move to the File Selection 
regi me. 
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• FTAM uses the exposed parameters filename and contents_type and 
does not use the correspondi ng val ues stored i n i nput_dcb- 
>attributes. 

• If thefileyou areselecting has access control, thefollowing conditions 
exist. 

• The requested_access parameter must be a subset of the val ues 
stored in actionjist field in struct Ft_access_control_element. 

• FTAM will detect conflicts between the initiatorjd and the 
identity field of the access_control_element. 

• The HP-UX implementation of FTAM does not use the 
file_passwords parameter. Other implementations might. 

Ftselecti ndcb 

struct Ft_select_in_dcb { 
struct Ft_attributes 
struct Ft_file_passwords 
Ft_account 

struct Ft_concurrency_control 


attributes; 
file_passwords; 
account; 

*concurrency_control; 


Ftselectoutdcb 

struct Ft_select_out_dcb { 


Uint32 


size; 

struct 

Api_rc 

result; 

enum 

Ft_state_result 

state_result; 

enum 

Ft_action_result 

action_resuit 

struct 

Ft_attributes 

attributes; 

struct 

Ft_diagnostic 

*diagnostic; 


ft select() Parameters 


ftselect() 

Parameter 


Type 


Description 


connection id 


filename 


Mandatory Uniquely identifies a specific connection to the 

Input filestore 


Mandatory Path nameof thefileyou areselecting; must be in 
Input the syntax of the real filestore 
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ftselect() 

Parameter 

Type 

Description 

request ed_access 

Mandatory 

1 nput 

Specifies the actions you want avail able for the 
connection (during the File Selection regime and 
those regimes nested within it) 

return_event_name 

Mandatory 

1 nput 

1 f the cal 1 is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is 0 (zero) 

input_dcb- 

>attributes 

Optional input 

FTAM does not use this field; provided for future 
use 

input_dcb-> 

file_passwords 

Optional 1 nput 

Passwords associated with the actions specified 
by requested_access 

i nput_dcb->account 

Optional 1 nput 

H P-UX responders accept, but ignore, this value 

input_dcb-> 

concurrency_control 

Optional 1 nput 

File access locks required on the actions specified 
in requested_access 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

state_result 

Output 

1 ndicates whether the request moved from the 
FTAM to the File Selection regime; if a failure 
returns, you will also receive an action result of 
FT_AR_PERMANENT_ERROR 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb- 

>attributes 

Output 

Contains values of the filename attribute of the 
file you selected HP-UX responders accept, but 
ignore, this value 

inout_dcb- 

>diagnostic 

Output 

Provides 1 SO-specificerror information 
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ft_open() (LLCS) 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_open (connection_id, processing_mode, contents_type, 
return_event_name, input_dcb, inout_dcb) 


Connection_id 
Ft_processing_mode 
struct Ft_contents_type 
Local_event_name 
struct Ft_open_in_dcb 
struct Ft_open_out_dcb 


connection_id; 
processing_mode; 
contents_type; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_open() after selecting or creating a file to access operations. 

• I nvokeft_open() in the File Selection regime to move to the File Open 
regi me. 

• During ft_connect(), you must negotiate the FT_FU_RE AD or 
FT_FU_WRITE functional_units to useft_open(). 

• The input_dcb->concurrency_control parameters must be the same or 
more restrictive than the input_dcb->concurrency_control 
parameters set on ft_create() and ft_select(). 

• If the file you are opening has access control, the foil owing conditions 
exist: 

• The processi ng_mode parameter must be a subset of the val ues 
stored in actionjist field in the access_control_element 
corresponding to the initiatorjd used to establish the connection. 

• The HP-UX implementation of FTAM does not use the 
file_passwords parameter. Other implementations might. 

Ftopenindcb 

struct Ft_open_in_dcb { 

struct Ft_concurrency_control *concurrency_control; 

} ; 
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F topenoutdcb 

struct Ft_open_out_dcb { 


Uint32 


size; 

struct 

Api_rc 

result; 

enum 

Ft_state_result 

state_result; 

enum 

Ft_action_result 

action_resuit; 

struct 

Ft_contents_type 

contents_type; 

struct 

Ft_concurrency_control 

*concurrency_c 

struct 

Ft_diagnostic 

*diagnostic; 


ft_open() Parameters 


ft_open() 

Parameter 

Type 

Description 

connection_id 

Mandatory 

Input 

Uniquely identifies a specific connection to the 
filestore 

processi ng_mode 

Mandatory 

Input 

Establishes a valid subset of actions negotiated in 
the File Selection regime 

contents_type 

Mandatory 

Input 

Specifies the document type 

return_event_name 

Mandatory 

Input 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is 0 (zero) 

input_dcb-> 
concurrency contro 

1 

Optional 1 nput 

File access locks required on the actions specified 
in requested_access 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 
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ft_open() 

Parameter 

Type 

Description 

inout_dcb-> 

state_result 

Output 

1 ndicates whether the request moved from the File 
Selection to the File Open regime; if a failure 
returns, you will also receive an action result of 
FT_AR_PERMANENT_ERROR 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb-> 

contents_type 

Output 

contents_type of the opened file (as accepted by 
the responder) 

inout_dcb-> 
concurrency contro 

1 

Output 

concurrency_control of the opened file (as accepted 
by the responder) 

inout_dcb- 
>di agnostic 

Output 

Provides 1 SO-specificerror information 


ft_close() (LLCS) 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_close (connection_id, return_event_name, input_dcb, 
inout_dcb) 


Connection_id 

Local_event_name 

char 

struct Ft_close_out_dcb 


connection_id; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_close() toclosea filewhen you finish processing it. After closing 
the file, the only actions you can perform on the file without re-opening it 
areft_deselect(), ft_delete(), ft_rattributes(), and ft_cattributes(). 


• Theft_close() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

• I nvokeft_close() in the File Open regime to return to the File 
Selection regime. 
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F tc I oseoutdcb 

struct Ft_close_out_dcb { 
Uint32 

struct Api_rc 

enum Ft_action_result 

struct Ft_diagnostic 

} ; 


size; 

result; 

action_resuit; 
*diagnostic; 


ft_close() Parameters 


ft_close() 

Parameter 

Type 

Description 

connectionjd 

M andatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

return_event_name 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value is 
0 (zero) 

input_dcb 

Optional input 

Contains no information; pass a NULL pointer 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Si ze (i n Octets) of the i nout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-U X— specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb- 
>di agnostic 

Output 

Provides 1 SO-specificerror information 
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ft_delete() (LLCS) 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_delete (connection_id, return_event_name, input_dcb, 
inout_dcb) 


Connection_id 

Local_event_name 

char 

struct Ft_delete_out_dcb 


connection_id; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Use ft_delete() to remove a file from the filestore. 

• Theft_delete() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

• I nvokeft_delete() in the File Selection regime to move back to the 
FTAM regime after deleting the file. 

• During ft_connect(), you must negotiate the FT_FU_LTD_M GMT 
functional_units to useft_delete(). 

• Duri ng ft_select(), ft_create(), and ft_fopen() you must specify 
FT_FA_DELETE_FILE in requested_accesstouseft_delete(). 


F tdel eteoutdcb 

struct Ft_delete_out_dcb { 
Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_charging 
struct Ft_diagnostic 

}; 


size; 

result; 

action_resuit; 

^charging; 

^diagnostic; 
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ft_delete() Parameters 


ft_close() 

Parameter 

Type 

Description 

connectionjd 

M andatory 

Input 

Uniquely identifies a specific connection to the 
filestore 

return_event_name 

Mandatory 

Input 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb 

Optional input 

Contains no information; pass a NULL pointer 

inout_dcb->size 

Mandatory input 
if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb-> 

charging 

Output 

HP-UX responders do not use charging, though it 
may contain information from other responders 

inout_dcb- 
>di agnostic 

Output 

Provides 1 SO-specificerror information 
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ft_deselect() 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_deselect (connection_id, return_event_name, input_dcb, 
inout_dcb) 


Connection_id 

Local_event_name 

char 

struct Ft_deselect_out_dcb 


connection_id; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Use ft_deselect() to deselect a file when you finish processing, but do not 
want to remove it. You must re-select the file to perform further actions 
on it. 

• Theft_deselect() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

• I nvokeft_deselect() in the File Selection regime to move back to the 
FTAM regime. 


F tdeselectoutdcb 

struct Ft_deselect_out_dcb { 
Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_charging 
struct Ft_diagnostic 

}; 


size; 

result; 

action_resuit; 

^charging; 

^diagnostic; 


ft deselect() Parameters 


ftdeselect() 

Parameter 


Type 


Description 


connection id 


M andatory U niquely identifies a specific connection to the 
Input filestore 


return_event_name Mandatory 
Input 


If the cal I is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is 0 (zero) 


input_dcb 


Optional input Contains no information; pass a NULL pointer 
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ft_deselect() 

Parameter 

Type 

Description 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb- 

xcharging 

Output 

HP-UX responders do not use charging, though it 
may contain information from other responders 

inout_dcb- 

>diagnostic 

Output 

Provides 1 SO-specificerror information 
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Opening and Closing Files (HLCS) 

Useft_fopen() and ft_fclose() toopen and close files, respectively, using 
only one high level call. 


ft_fopen() Either selects or creates, and then opens a file 

ft_fclose() Closes a file, and then either deselects or deletes a 

file 


ft_fopen() (HLCS) 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_fopen (connection_id 


Connection_id 
Ft_filename 
enum Ft_file_status 

Ft_file_actions 
struct Ft_contents_type 
Local_event_name 
struct Ft_fopen_in_dcb 
struct Ft_fopen_out_dcb 


status, 

, return_event_name 


connection_id; 
filename; 
file_status; 
requested_access; 
contents_type; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


filename, file_ 
requested_access, contents_type 
input_dcb, inout_dcb) 


Useft_fopen() to create or select a file and then open it with one cal I 
(rather than invoking the low level calls ft_select() or ft_create() with 
ft_open()). 

• I nvokeft_fopen() in the FTAM regime to move to the File Open 
regi me. 

• If the file already exists, thefile_status parameter determines 
whether a new file is created or the request fails. (Refer to the 
"Ft_file_status" section in the "FTAM Data Structures"chapter for 
options on setting this field.) 
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• If the file you are selecting and opening has access control, the 
following conditions exist. 

• The requested_access parameter must be a subset of the val ues 
stored in action_list field in the access_control_element 
corresponding to the initiatorjd used to establish the connection. 

• FTAM will detect conflicts between the initiatorjd and the 
identity field of the access_control_element. 

• The HP-UX implementation of FTAM does not use the 
file_passwords parameter. Other implementations might. 

• If you create a new file, the returned file attributes are in the 
i nout_dcb->attri butes. 

• FTAM uses the exposed parameters filename and contents_type and 
does not use input_dcb->attributes.values.filename and input_dcb- 
>attri butes. val ues.contents_type. 

• I f you do not specify permitted_acti ons, FTAM uses requested_access 
for permitted_actions. 

• The processi ng_mode parameter used when the file is opened 
includes all file actions set in requested_access that are valid in the 
File Open regime. 

• If you are selecting and opening a file, but do not know what the 
document type is, set contents_type.contents_form to 
FT_CONTENTS_UN KNOWN. 

F tfopeni ndcb 

struct Ft_fopen_in_dcb { 

struct Ft_attributes 
struct Ft_concurrency_control 
struct Ft_file_passwords 
Ft_account 


attributes; 
*concurrency_control; 
file_passwords; 
account; 
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F tfopenoutdcb 


struct Ft_fopen_out_dcb { 

Uint32 

struct Api_rc 

enum Ft_state_result 

enum Ft_action_result 

struct Ft_attributes 

struct Ft_concurrency_control 

struct Ft_diagnostic 

} ; 


size; 

result; 

state_result; 

action_resuit; 

attributes; 

*concurrency_control; 

*diagnostic; 


ft_fopen() Parameters 


ft_fopen() 

Parameter 

Type 

Description 

connection_id 

M andatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

filename 

M andatory 

1 nput 

Path name of the file you are opening; must be 
in the syntax of the real filestore 

file_status 

M andatory 

1 nput 

Determines the action to take if the file already 
exists 

requested_access 

M andatory 

1 nput 

Specifies the actions you want to perform on the 
file 

contents_type 

M andatory 

1 nput 

Specifies the document type of the file you are 
creating or opening 

return_event_name 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb- 

>attributes 

Optional 

Uniquely identifies the file you arecreating and 
opening; do not use input_dcb- 
>attributes.values.filenameor input_dcb- 
>attri butes.val ues.contents_type 

input_dcb-> 
concu r ren cy_cont r ol 

Optional 

File access locks required on the actions 
specified in requested_access 

input_dcb-> 

file_passwords 

Optional 

Passwords associated with the actions specified 
by requested_access 
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ft_fopen() 

Parameter 

Type 

Description 

i n put_dcb- >accou nt 

Optional 

H P-UX responders accept, but ignore, this value 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

state_result 

Output 

1 ndicates whether the request moved through 
regimes; if a failure returns, you will also 
receive an action result of 
FT_AR_PERMANENT_ERROR 

inout_dcb-> 

action_result 

Output 

Specifies the overall successor failure of the 
request 

inout_dcb- 
>attributes 

Output 

If you created the file, contains values of the 
attributes of the file (those attributes accepted 
by the responder); if you selected the file, 
contains values of the filename and 
contents_type attributes 

inout_dcb-> 
concu r ren cy_cont r ol 

Output 

concurrency_control of the opened file (as 
accepted by the responder) 

inout_dcb- 

Output 

Provides 1 SO-specificerror information 


>di agnostic 
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ft_fclose() (HLCS) 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_fclose (connection_id, delete_action, 

return_event_name, input_dcb, inout_dcb) 


Connection_id 

enum Ft_delete_action 

Local_event_name 

char 

struct Ft_fclose_out_dcb 


connection_id; 
delete_action; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_fclose() to close a file, and then either deselector delete it (rather 
than invoking the low level ft_close() function with ft_deselect() or 
ft_delete()). 

• I nvokeft_fclose() in the File Open regime to move back to the FTAM 
regi me. 

• Thedelete_action parameter determines whether thefile is deleted or 
deselected. 

• Theft_close() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

F t_fc I oseoutdcb 

struct Ft_fclose_out_dcb { 

Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_diagnostic 


size; 

result; 

action_result; 
*diagnostic; 
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ft_fclose() Parameters 


ftfdoseO 

Parameter 

Type 

Description 

connectionjd 

M andatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

delete_action 

M andatory 

1 nput 

Determines whether to delete or deselect the file 

ret u r n_event_n a me 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, thevalueis 
0 (zero) 

input_dcb 

Optional input 

Contains no information; pass a NULL pointer 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the outcome 
of the operation: result_code and vendor_code (H P- 
UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall successor failure of the 
request 

inout_dcb- 
>di agnostic 

Output 

Provides 1 SO-specificerror information 
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Reading and Changing Attributes 
(LLCS) 

Usetheft_rattributes() and ft_cattributes() to read and change 
attributes using low level calls. 

If you are already in the File Selection regime, it is faster and easier to 
use low level calls to read and change attributes than to use high level 
calls (which re-connect and re-select). I n other cases, the high level calls 
may be easier to use. 

ft_rattributes() (LLCS) 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_rattributes (connection_id, return_event_name, input_dcb, 
inout_dcb) 

Connection_id 
Local_event_name 
char 

struct Ft_rattributes_out_dcb 

Useft_rattributes() to read attributes. 

• I nvokeft_rattributes() in the File Selection regime; you do not move 
to another regi me. 

• During ft_connect(), you must negotiate the FT_FU_LTD_M GMT 
functional_units to use ft_rattri butes(). 

• During ft_select(), you must specify FT_FA_READ_ATTRI BUTE in 
request ed_access. 

• Useinput_dcb->attribute_names to specify which attributes you want 
to read. The attributes you read return in inout_dcb-attributes. 

• FI P-UX responders return the indication no value available (0) for the 
attributes legal_qualification, private_use, future_filesize, and 
storage_account. 


connection_id; 
return_event_name; 
*input_dcb; 
**inout_dcb; 
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F trattr i butesi ndcb 

struct Ft_rattributes_in_dcb { 

Ft_attribute_names attribute_names; 

} ; 


F trattr i butesoutdcb 

struct Ft_rattributes_out_dcb 
Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_attributes 
struct Ft_diagnostic 

} ; 


size; 

result; 

action_resuit; 

attributes; 

*diagnostic; 


ft rattributesO Parameters 


ft_rattributes() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 

1 nput 

Uniquely identifies a specific connection tothe 
filestore 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is zero 

input_dcb-> 

attribute_names 

Optional Input 

Indicates the file attributes to read; default is all 
file attributes associated with the attribute groups 
negotiated on ft_connect() 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 


outcome of the operation 
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ft_rattributes() 

Parameter 

Type 

Description 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb- 

>attributes 

Output 

Contains values of the attributes of the file you 
read (those attributes accepted by the responder) 

inout_dcb- 
>di agnostic 

Output 

FI olds 1 SO-specific error information 


ft_cattributes() (LLCS) 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_cattributes (connection_id, 
inout_dcb) 

Connection_id 
Local_event_name 
struct Ft_cattributes_in_dcb 
struct Ft_cattributes_out_dcb 


return_event_name, input_dcb 


connection_id; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Use ft_cattributes() to change file attributes. For example, you can 

change an attribute such as access_control to allow a specific user to 

access a file. 

• I nvokeft_cattributes() in the File Selection regime; you do not move 
to another regi me. 

• During ft_connect(), you must negotiate the FT_FU_ENFI_M GMT 
functional_units to use ft_cattri butes(). 

• During ft_select(), you must specify FT_FA_CFI ANGE_ATTRI BUTE 
in requested_access. 

• The attributes_ groups negotiated on theft_connect() request dictates 
the attributes you can change. 

• The input_dcb->attribute_names parameters takes precedence over 
the input_dcb->attributes.mask field. 
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Attributes You Can Change 

access_control 

fil e_avai I abi I ity 

filename 

future_filesize* 

legal_qualification* 

private_use* 

storage_account* 


Attributes You Cannot 
Change 

contents_type 

date_ti me_of_attri bute_mod 
date_ti me_of_creati on 
date_ti me_of_modificati on 
date_ti me_of_read 
fil esi ze 

identity_of_attri bute_mod 
i dentity_of_creator 
identity_of_modifier 
i dentity_of_reader 
permitted_actions 


* H P-UX responders accept, but ignore, these values. 

F tcattr i butesi ndcb 

struct Ft_cattributes_in_dcb { 

Ft_attribute_names attribute_names; 

struct Ft_attributes attributes; 

}; 


F tcattr i butesoutdcb 

struct Ft_cattributes_out_dcb 
Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_attributes 
struct Ft_diagnostic 

} ; 


size; 

result; 

action_resuit; 

attributes; 

*diagnostic; 
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ft cattributesO Parameters 


ft_cattributes() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is 0 (zero) 

input_dcb-> 

attribute_names 

Mandatory 

1 nput 

Mask that indicates which file attributes to 
change 

input_dcb- 

>attributes 

Mandatory 

1 nput 

Specifies the val ues of the attri butes to change; 
attributes.values contains new values for each 
attribute specified in attribute_names 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overal 1 success or fai 1 ure of the 
request 

inout_dcb- 
>attributes 

Output 

Contai ns val ues of the attri butes you changed 
(those attributes accepted by the responder) 

inout_dcb- 
>di agnostic 

Output 

Provides 1 SO-specificerror information 
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Locating and Erasing FTAM Files 

Usetheft_locate() to locate FADUs (FTAM-2) and ft_erase() to erase 
FTAM files. 

ft_locate() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_locate (connection_id, fadu_identity, 

return_event_name, input_dcb, inout_dcb) 
Connection_id connection_id; 

Ft_fadu_identity fadu_identity; 

Local_event_name return_event_name; 

char *input_dcb; 

struct Ft_locate_out_dcb **inout_dcb; 


Useft_locate() to locate a specific FADU within a file. Hence, use 
ft_locate() only on FTAM-2 document types. For example, you might 
want to locatethe current FADU in an FTAM-2 file so that you can read 
it. 


• Theft_locate() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

• I nvokeft_locate() in the FileOpen regime; you do not move to another 
regi me. 

• During ft_connect(), you must negotiate the FT_FU_FI LE_ACCESS 
functional_units to useft_locate(). 

F tl ocateou t_dc b 

struct Ft_locate_out_dcb { 

Uint32 

struct Api_rc 
enum Ft_action_result 
struct Ft_fadu_identity 
struct Ft_diagnostic 

} ; 


size; 
result; 

action_result; 
*fadu_identity; 
*diagnostic; 
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ftlocateO 

Parameter 

Type 

Description 

connectionjd 

Mandatory 1 nput 

Uniquely identifies a specific connection to the 
filestore 

fadu_identity 

Mandatory 1 nput 

Identifies the FADU to locate (FTAM-2 only) 

return_event_name 

Mandatory 1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is 0 (zero) 

input_dcb 

Optional input 

Contains no information; pass a NULL pointer 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb-> 

fadu_identity 

Output 

fadujdentity of the FADU you located (FTAM-2 
only) 

i nout_dcb- 
xli agnostic 

Output 

Provides 1 SO-specificerror information 
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ft_erase() 


#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
Return_code 

ft_erase (connection_id, fadu_identity, 
input_dcb, inout_dcb) 

Connection_id 
Ft_fadu_identity 
Local_event_name 
char 

struct Ft_erase_out_dcb 


return_event_name, 

connection_id; 
fadu_identity; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Use ft_erase() to erase a file's contents; attri butes are not erased. 

• To erase the entire file's contents, thefadujdentity.fadujocation 
must be FT_FI RST for FTAM-1, FTAM-3, and INTAP-1 and must be 
FT_BEGI N for FTAM-2. 

• Theft_erase() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

• I nvoke ft_erase() i n the File Open regi me; you do not move to another 
regi me. 

• During ft_connect(), you must negotiate the FT_FU_FI LE_ACCESS 
functional_units to use ft_erase(). 

• Duringft_open(), you must specify FT_PM_ERASE in 
processi ng_mode to use ft_erase(). 

F teraseoutdcb 

struct Ft_erase_out_dcb { 

Uint16 

struct Api_rc 
enum Ft_action_result 
struct Ft_diagnostic 


size; 

result; 

action_resuit; 
*diagnostic; 
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ft erase() Parameters 


ft_locate() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 

1 nput 

Uniquely identifies a specific connection tothe 
filestore 

fadu_identity 

Mandatory 

1 nput 

1 dentifies the FADU to erase 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value 
is zero. 

input_dcb 

Optional input 

Contains no information; pass a NULL pointer 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb- 
>di agnostic 

Output 

Provides 1 SO-specificerror information 
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Grouping LLCS FTAM Functions 

Useft_bgroup() and ft_egroup() to begin and end the grouping of low 
level FTAM functions and thus, increase performance. Theftamjnit 
places these functions into one presentation service data unit (PSDU) 
before sending it across the network. 

For a group to be successful, all functions moving from one regime to 
another must be successful (regardless of whether the calls that do not 
move through regimes succeed). 

If a failure occurs on a function that crosses regimes and if the 
SUCCESS count does not equal or exceed threshold, no remaining calls, 
except ft_egroup(), are processed and you receive an error. 

Allowable Groupings 

Refer to the foil owing guidelines for grouping FTAM functions and for 
reading the foil owing table. The table lists the legal groupings with the 
associated sequence of LLCS functions (from left to right). 


EXAMPLE: The first grouping (#1) in the table reads as follows. 

1. Call ft_bgroup(). 

2. Call either ft_create() if thefiledoes not exist or 
ft_select() if it does. 

3. Call either or both ft_rattributes() and 
ft_cattributes(). 

4. Call ft_open() followed by ft_egroup(). 

• All groups must begin with ft_bgroup() and end with ft_egroup(). 

• The first function you want tocall after ft_bgroup() determines which 
regime you must be in tocall ft_bgroup(). 

• You must call all functions within the group asynchronously except 
for ft_egroup(), which can be synchronous or asynchronous. 

• If morethan one function is listed in a "Mandatory" column, you 
must perform both functions in the order listed. 
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• You can specify either or both optional functions, or can choose not to 
use them. If you call both optional functions, you must do so in the 



order given in 

the table. 



Mandatory 

Beginning 

Functions 

Must Have 
One of these 
Functions 

Optional 

Functions 

Must Have 
One of these 
Functions 

Mandatory 

Ending 

Functions 

#1 ft_bgroup() 

ft_select() 

ft_create() 

ft_rattributes() 

ft_cattributes() 

ft_open() 

ft_egroup() 

fS ft_bgroup() 

ft_close() 

ft_rattributes() 

ft_cattributes() 

ft_deselect() 

ft_delete() 

ft_egroup() 

#3 ft_bgroup() 

ft_select() 

ft_create() 

ft_rattributes() 

ft_cattributes() 

ft_deselect() 

ft_delete() 

ft_egroup() 

M ft_bgroup() 

ft_select() 

ft_create() 

ft_rattributes() 

ft_cattributes() 


ft_egroup() 

#5 ft_bgroup() 


ft_rattributes() 

ft_deselect() 

ft_egroup() 


ft_cattributes() ft_delete() 

The legal groupings are restricted by theservice_class. Refer to the 
above table and the following list to determine these restrictions. 

• If you select FT_SC_TRANSFER, you must use the #1 or #2 
groupings. 

• If you select FT_SC_MANAGEMENT, you must use the #3 grouping. 

• If you select FT_SC_TRANSFER_AND_MGMT, you must use the #1, 
#2, or #3 groupings. 

• If you select FT_SC_ACCESS, you can use any of the groupings. 

If you select the service_class FT_SC_TRANSFER, 
FT_SC_MANAGEMENT, or FT_SC_TRANSFER_AND_MGT, you must 
use FT_FU_GROUPI NG in thefunctional_units parameter. 
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ftbgroupO 

Parameter 

connectionjd 

threshold 


ftbgroupO 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_bgroup (connection_id, threshold, return_event_name, 
input_dcb, inout_dcb) 

Connection_id connection_id; 

Uint32 threshold; 

L o c al_eve nt_n ame return_event_name; 

char *input_dcb; 

struct Ft_bgroup_out_dcb **inout_dcb; 

Issue an asynchronous ft_bgroup() to start a set of grouped functions. 

• You cannot nest an ft_bgroup() function within another ft_bgroup() 
function (i.e., you cannot invokeft_bgroup() within another set of 
grouped functions). 

• During ft_connect(), you must negotiate the FT_FU_GROU PI NG 
functional_units to use ft_bgroup(). 

F tbgrou poutdcb 

struct Ft_bgroup_out_dcb { 

Uint32 size; 

struct Api_rc result; 

}; 


ft bgroupO Parameters 


Type 


Description 


Mandatory I nput Uniquely identifies a specific connection to the 
filestore 

Mandatory I nput Specifies how many functions that change 

regimes must be successful for the group to be 
successful; set to a value between 1 and 5 
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return_event_na 

me 

inout_dcb->size 
inout dcb->result 
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Type 


Description 


Mandatory Input Uniquely identifies the asynchronous call 


Mandatory input Size (in Octets) of the inout_dcb structure and 
if usi ng i nout_dcb data 


Output 


Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-U X— specific error) 


ftegroupO 

#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_egroup (connection_id, return_event_name, input_dcb, 
inout_dcb) 


Connection_id 

Local_event_name 

char 

struct Ft_egroup_out_dcb 


connection_id; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_egroup(), either synchronously or asynchronously, to end a set of 

grouped functions. 

• During ft_connect(), you must negotiate the FT_FU_GROU PI NG 
functional_units to useft_egroup(). 

• An ft_egroup() is successful only if ft_bgroup() succeeds and if the 
threshold number of requests succeeds. 

F tegrou p_ou t_dc b 

struct Ft_egroup_out_dcb { 

Uint32 size; 

struct Api_rc result; 


306 


Chapter 7 



Managing and Accessing HP FTAM/9000 Files 

Grouping LLCS FTAM Functions 


ftegroupO Parameters 


ftegroupO 

parameter 

Type 

Description 

connectionjd 

Mandatory 

Input 

Uniquely identifies a specific connection to the 
filestore 

return_event_na 

me 

Mandatory 

Input 

If the call is asynchronous, uniquely identifies the 
function call; if the call is synchronous, the value is 
zero 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the outcome 


of the operation: result_code and vendor_code (H P- 
UX—specific error) 
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Transferring HP FTAM/9000 Data 


After opening a file, you can send and receive FTAM data. Refer to the 
"Example Programs" chapter for model programs using the functions 
described in the chapter. 
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C hapter Overview 

This chapter describes the sequence of transferring data and describes 
the foil owing functions in the order listed. 


Task to Perform 

Function Used 
to Perform the 
Task 

Description 

Reading Data 

ft_read() 

Specify the information to be read 


ft_rdata() 

Receive data that was requested in ft read() and 
QOS=0 


ft_rdataqos() 

Receive data that was requested in ft read() and 
QOS>0 

Writing Data 

ft_write() 

Specify the information to write 


ft_sdata() 

Send data that was requested in ft_write() 

Ending Data 

T ransfer 

ft_edata() 

E nd the sendi ng of data 


ft_etransfer() 

End data transfer 


ft_cancel() 

Cancel the transferring of data 


ft_rcancel() 

Acknowledge the cancel of data being 


transferred 


NOTE This chapter does not explain the parameter structures. For detailed 

structure information (parameter settings), refer tothe "FTAM Data 
Structures" chapter. 
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Sequence of Transferri ng Data 

Sequences to use when transferring data are as follows. 


1. ft_read() 1. ft_write() 

2. ft_rdata() (multiple) 2. ft_sdata() (multiple) 

3. ft_etransfer() 3. ft_edata() 

4. ft_etransfer() 

• I f you i nvoke ft_read() or ft_write(), you must exit the regi me by 
invoking ft_etransfer(). 

• I f you i nvoke ft_sdata(), you must end the sendi ng of data by i nvoki ng 
ft_edata(). 

• To prematurely terminate a data transfer after issuing ft_read() or 
ft_write(), call ft_cancel(). 

• You can receive a cancel indication any time; if you receive one, 
acknowledge it by calling ft_rcancel(). If you receivea cancel 
indication, you automatically exit the Data Transfer regi me and move 
into the File Open regime. 
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Reading Data 

Useft_read() to identify what you want to read. To receive the identified 
information from the responder, call ft_rdata() to tel I ftamjnit the 
number of data elements you want to receive. The ftamjnit gathers and 
returns the information requested. 


ft_read() 


#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 


Return_code 

ft_read (connection_id, fadu 
return_event_name, 
Connection_id 
struct Ft_fadu_identity 
enum Ft_access_context 
Local_event_name 
char 

struct Ft_read_out_dcb 


.identity, access_context, 
nput_dcb, inout_dcb) 

connection_id; 
fadu_identity; 
access_context; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_read() to identify the FADUs you want to read and to request that 
data be sent. Remember, FADUs may contain structure and data. Since 
FTAM-1, FTAM-3, and NBS-9 filetypefiles contain only single FADUs, 
you must read theentirefile. You can read individual FADUs within 
FTAM-2 files. (Refer to the "FI P-UX FTAM Overview" chapter for a 
description of FADUs. Refer to the "FTAM Data Structures" chapter for 
information on Ft_fadu_identity.) 

• I nvokeft_read() in the File Open regime to move to the Data Transfer 
regi me. 

• During ft_connect(), you must negotiate the FT_FU_RE AD 
functional_units to useft_read(). 

• Duringft_create() and ft_select(), you must request FT_FA_READ in 
request ed_access. 

• Theft_read() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

• To read an FTAM-1, FTAM-3, INTAP-1, or NBS-9 file, set 
fadujdentity of FT_FI RST. To read an entire FTAM-2 file, set 
fadujdentity to FT_BEGI N. To read a FADU within an FTAM-2 file, 
set fadujdentity to FT_F I RST or FT_NEXT. 


Chapter 8 


313 




Transferring HP FTAM/9000 Data 

Reading Data 


• If you specify FT_UNSTRUCTURED_ALL_DATA_UNITS in 

access_context for FTAM-2 files, you receive only the data elements, 
not the node descriptors (structuring information). If you specify 
FT_FLAT_ALL_DATA_UNITS in access_context for FTAM-2 files, 
you receive both data elements and node descriptors. 

Ftreadoutdcb 

struct Ft_read_out_dcb { 

Uint32 size; 

struct Api_rc result; 

} ; 


ft_read() Parameters 


ft_read() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

fadu_identity 

Mandatory 

1 nput 

1 dentifies the FADU to read 

access_context 

Mandatory 

1 nput 

Specifies the access context; depends on the 
document type 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is zero 

input_dcb 

Optional 1 nput 

Contains no information; pass a NULL pointer 

inout_dcb->5ize 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 


outcome of the operation: result_code and 
vendor_code (FI P-UX—specific error) 
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ft_rdata() 


#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
Return_code 

ft_rdata (connection_id, des_requested, 
inout_dcb) 

Connection_id 
Uint16 

L o c al_eve nt_name 
struct Ft_rdata_out_dcb 


return_event_name, 

connection_id; 
des_requested; 
return_event_name; 
**inout_dcb; 


Use ft_rdata() to receive the data you requested on ft_read(). Issuing 
ft_rdata() controls the number of data elements you read (i.e., controls 
the flow of information). You may have to call ft_rdata() several times to 
read the entire contents of a file. The information returns in the 
inout_dcb->data_unit parameter. 

Since FTAM-1, FTAM-3, and INTAP-1 files contain only single FADUs, 
you must read theentirefile. You can read individual FADUs within 
FTAM-2files. (Refer to the "FTAM Data Structures" chapter for 
Ft_data_unit information.) 

• I nvokeft_rdata() in the Data Transfer regime after invoking 
ft_read(); you do not move to another regime. 

• The des_requested parameter specifies the maximum number of data 
elements you want to receive. 

• During ft_connect(), you must negotiate the FT_FU_RE AD 
functional_units to useft_rdata(). 

• If the inout_dcb->data_unit->structure_id equals FT_DATA_END, 
you reached the end of the file. 

• If the inout_dcb->data_unit->structure_id equals FT_CANCEL_IND, 
the responder cancelled the data transfer. Call ft_rcancel() to respond 
to the cancel indication; do not send another ft_rdata(). 

F trdataoutdcb 

struct Ft_rdata_out_dcb { 


Uint16 


size; 

struct 

Api_rc 

result; 

Uint32 


des_received; 

struct 

Ft_data_unit 

*data_unit; 

enum 

Ft_action_result 

action_resuit; 

struct 

Ft_diagnostic 

*diagnostic; 
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ft_rdata() Parameters 


ft_rdata() 

Parameter 

Type 

Description 

connectionjd 

M andatory 

1 nput 

Uniquely identifies a specific connection to the 
filestore 

des_requested 

M andatory 

1 nput 

Maximum number of data elements you want to 
receive 

return_event_name 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is zero 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc contai ni ng the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

des_received 

Output 

N umber of data elements received by this 
request if it is successful 

inout_dcb->data_unit 

Output 

Contains the returned data 

inout_dcb-> 

action_result 

Output 

Specifies the overall success or failure of the 
request 

inout_dcb->diagnostic 

Output 

Provides 1 SO-specific error information 
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Reading Data 


ft_rdataqos() 

#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_rdataqos (src_connection_id, dest_connection_id, 

des_requested, return_event_name, inout_dcb) 
Connection_id src_connection_id; 

Connection_id dest_connection_id; 

Uintl6 des_requested; 

Local_event_name return_event_name; 

struct Ft_rdata_out_dcb **inout_dcb; 


Useft_rdataqos() to receive the data you requested on ft_read(). Issuing 
ft_rdataqos() controls the number of data elements you read (i.e., 
controls the flow of information). You may have to call ft_rdataqos() 
several ti mes to read the enti re contents of a file. The i nformation 
returns in the inout_dcb->data_unit parameter. 

Since FTAM-1, FTAM-3, and INTAP-1 files contain only single FADUs, 
you must read theentirefile. You can read individual FADUs within 
FTAM-2files. (Refer to the "FTAM Data Structures" chapter for 
Ft_data_unit information.) 

• Both ft_rdataqos() and ft_rdata() perform the same function. 

FI owever, ft_rdataqos() is used if QOS is set to 1 or 2 while ft_rdata() 
is used if QOS is set to 0. Also, in ft_rdataqos(), both the source and 
destination connectionjds are passed while in ft_rdata(), only one 
connectionjd is passed. 

• I nvokeft_rdataqos() in the Data Transfer regime after invoking 
ft_read(); you do not move to another regime. 

• The des_requested parameter specifies the maximum number of data 
elements you want to receive. 

• During ft_connect(), you must negotiate the FT_FU_RE AD 
functional_units to useft_rdataqos(). 

• If the inout_dcb->data_unit->structure_id equals FT_DATA_END, 
you reached the end of the file. 

• If the inout_dcb->data_unit->structure_id equals FT_CANCEL_I ND, 
the responder cancelled the data transfer. Call ft_rcancel() to respond 
to the cancel indication; do not send another ft_rdataqos(). 
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Reading Data 


F t_rdataqos_out_dcb 

struct Ft_rdataqos_out_dcb { 


Uint16 


size; 

struct 

Api_rc 

result; 

Uint32 


des_received; 

struct 

Ft_data_unit 

*data_unit; 

enum 

Ft_action_result 

action_resuit; 

struct 

Ft_diagnostic 

*diagnostic; 


ftrdataqosO Parameters 


ftrdataqosO 

Parameter 

Type 

Description 

src_connection_id 

M andatory 

1 nput 

Uniquely identifies the source connection to the 
filestore 

dest_con necti on_i d 

M andatory 

1 nput 

Uniquely identifies the destination connection to 
the filestore 

des_requested 

M andatory 

1 nput 

Maximum number of data elements you want to 
receive 

return_event_name 

M andatory 

1 nput 

If the call is asynchronous, uniquely identifies 
the function call; if the call is synchronous, the 
value is zero 

inout_dcb->5ize 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the inout_dcb structure and 
data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc containing the 
outcome of the operation: result_code and 
vendor_code (H P-UX—specific error) 

inout_dcb-> 

des_received 

Output 

N umber of data elements received by this 
request if it is successful 

inout_dcb->data_unit 

Output 

Contains the returned data 

inout_dcb-> 

action_result 

Output 

Specifies the overal 1 success or fai 1 ure of the 
request 

i nout_dcb->di agnostic 

Output 

Provides 1 SO-specificerror information 
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Writing Data 

Useft_write() and ft_sdata() to write data. 

• Useft_write() to request permission to write information toafileand 
to specify what to write (from the initiator to the responder). 

• U se ft_sdata() to send data. 


ft_write() 


#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
Return_code 

ft_write (connection_id, fadu_identity, 
return_event_name, input_dcb. 
Connection_id 
struct Ft_fadu_identity 
enum Ft_fadu_operation 
Local_event_name 
char 

struct Ft_write_out_dcb 


fadu_operation, 
inout_dcb) 
connection_id; 
fadu_identity; 
fadu_operation; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_write() to write data to a specific filestore by identifying a FADU 
to which you want to write. You can only write to a file as follows. 


FTAM-1, FTAM-3, and 
INTAP-1 

• To write over the existing 
FADU, 

fadu_i denti ty.fadu_l ocati on 
must be FT_FI RST and 
fadu_operation must be 
FT_REPLACE. 

• To write to the end of the 
FADU, 

fadu_i denti ty.fadu_l ocati on 
must be FT_FI RST and 
fadu_operation must be 
FT EXTEND. 


FTAM-2 

You can only write to the end of 
the file. The 

fadujdentity.fadujocation must 
be FT_E N D and fadu_operati on 
must be FT INSERT. 
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Writing Data 


• I nvokeft_write() in the File Open regime to move to the Data 
Transfer regime. 

• During ft_connect(), you must negotiate the FT_FU_WRITE 
functional_units to useft_write(). 

• During ft_create() and ft_select(), you must set requested_access 
accordi ng to the document type. 


FTAM-1, FTAM-3, and 
INTAP-1 

FT_FA_EXTEND FT_FA_I NSERT 

FT_FA_REPLACE 

• Duri ng ft_open(), you must set processi ng_mode accordi ng to the 
document type. 


FTAM-1 and FTAM-3 FTAM-2 

FT_PM_EXTEND FT_PM_I NSERT 

FT_PM_REPLACE 

• Theft_write() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 

F twri teou t_dc b 

struct Ft_write_out_dcb { 

Uint32 size; 

struct Api_rc result; 

}; 
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Writing Data 


ft_write() Parameters 


ft_write() 

Parameter 

Type 

Description 

connection_id 

Mandatory 

1 nput 

U niquely identifies a specific 
connection to the filestore 

fadu_identity 

Mandatory 

1 nput 

Identifies the FADU to which 
you write 

fadu_operation 

Mandatory 

1 nput 

Specifies the acti on you are 
taking on a file; depends on 
the document type 

return_event_na 

me 

Mandatory 

1 nput 

If the call is asynchronous, 
uniquely identifies the 
function call; if the call is 
synchronous, the value is zero 

input_dcb 

Optional 1 nput 

Contains no information; pass 
a N U L L poi nter 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the 
inout_dcb structure and data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc 
contai ni ng the outcome of the 
operation: result_code and 
vendor_code 
(H P-U X— specific error) 


ft sdata() 


#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_sdata (connection_id, data_unit, return_event_name, 
inout_dcb) 

Connection_id connection_id; 

struct Ft_data_unit *data_unit; 

Local_event_name return_event_name; 

struct Ft_sdata_out_dcb **inout_dcb; 
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Useft_sdata() to send data units to a file. You can send a maximum of 14 

data units linked together for each ft_sdata() function call. 

• I nvoke ft_sdata() i n the Data Transfer regi me; you do not move to 
another regime. 

• During ft_connect(), you must negotiate the FT_FU_WRITE 
functional_units to use ft_sdata(). 

• During ft_create() and ft_select(), you must set requested_access 
accordi ng to the document type. 


FTAM-1, FTAM-3, and 
INTAP-1 


FTAM-2 


FT_FA_EXTEND FT_FA_I NSERT 

FT FA REPLACE 


• If you call ft_sdata() asynchronously and then receive the 
FTE008_NO_CON_RESOURCES error, either call ft_nwcleared() to 
determine when the resources are free or re-issue ft_sdata(). 

• The total amount of data sent per ft_sdata() call is limited to about 7K 
octets. The function will return FTE101_BUFF_TOO_BIG if this 
threshold is exceeded. 


F tsdataoutdcb 

struct Ft_sdata_out_dcb { 
Uint32 

struct Api_rc 

enum Ft_action_result 

struct Ft_diagnostic 

} ; 


size; 
result; 

action_resuit; 
*diagnostic; 
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Writing Data 


ft sdataQ Parameters 


ft_sdata() 

Parameter 

Type 

Description 

connection_id 

Mandatory 

1 nput 

U niquely identifies a specific 
connection to the filestore 

data_unit 

Mandatory 

1 nput 

Linked list containing the 
data units to send; use 
data_unit to control theflow 
of data 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, 
uniquely identifies the 
function call; if the call is 
synchronous, the value is 
zero 

inout_dcb->size 

Mandatory 
input if using 
i nout_dcb 

Size (in Octets) of the 
inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc 
contai ni ng the outcome of 
the operation: result_code 
and vendor_code 
(H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success 
or failure of the request 

inout_dcb->diagnostic 

Output 

Provides 1 SO-specific error 
information 
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E ndi ng Data Transfer 

Useft_edata() and ft_etransfer() to terminate data transfers in an 
orderly manner. Useft_cancel() to prematurely terminate a data transfer 
after issuing an ft_read() or ft_write() request, and useft_rcancel() to 
respond to a cancel indication. 


ft edata() 


#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_edata (connection_id, return_event_name, input_dcb, 
inout_dcb) 

Connection_id connection_id; 

Local_event_name return_event_name; 

char *input_dcb; 

struct Ft_edata_out_dcb **inout_dcb; 


After issuing the necessary number of ft_sdata() functions, call ft_edata() 
to signal the responder you are no longer sending data (i.e., you 
completed sending the data unit). 

You must call ft_edata() before calling ft_etransfer(); after calling 
ft_edata(), you can no longer call ft_sdata() until you call ft_etransfer() 
followed by ft_write(). 

• I nvoke ft_edata() i n the Data Transfer regi me; you do not move to 
another regime. 

F tedata_i ndcb 

struct Ft_edata_in_dcb { 

enum Ft_action_result 
struct Ft_diagnostic 

}; 


F tedataou t_dc b 

struct Ft_edata_out_dcb { 
Uint32 

struct Api_rc 

enum Ft_action_result 

struct Ft_diagnostic 

} ; 


action_resuit; 
*diagnostic; 


size; 
result; 

action_result; 
*diagnostic; 
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Ending Data Transfer 


ft_edata() Parameters 


ft_edata() 

Parameter 


Type 


Description 


connectionjd 

Mandatory 

1 nput 

Uniquely identifies a 
specific connection to the 
filestore 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, 
uniquely identifies the 
function call; if the call is 
synchronous, the value is 
zero 

input_dcb- 

>action_result 

Mandatory 

1 nput 

Specifies that all data was 
sent 

i n put_dcb- >di agnost i c 

Optional 1 nput 

1 SO-specific error 
information; HP-UX 
responders accept, but 
ignore this value 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the 
inout_dcb structure and data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc 
contai ni ng the outcome of 
the operation: result_code 
and vendor_code 
(H P-UX—specific error) 

inout_dcb-> 

action_result 

Output 

Specifies the overall success 
or fai 1 ure of the request 

i nout_dcb->diagnostic 

Output 

Provides 1 SO-specific error 
information 
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ft_etransfer() 

#include %</opt/ftam/include/map.h> 


#include %</opt/ftam/include/: 
Return_code 

ft_etransfer (connection_id, 
inout_dcb) 

Connection_id 

Local_event_name 

char 

struct Ft_etransfer_out_dcb 


Lapf tam. h> 

eturn_event_name, input_dcb, 

connection_id; 
return_event_name; 
*input_dcb; 
**inout_dcb; 


Useft_etransfer() to end the transferring of data (ft_read() or ft_write()). 
Useft_etransfer() in one of the foil owing sequences. 


ft_read() ft_rdata() 
ft_etransfer() 


ft_write() ft_sdata() ft_edata() 
ft_etransfer() 


• I nvoki ng ft_etransfer() i n the Data Transfer regi me moves you back 
to the File Open regime. 

• Theft_etransfer() input_dcb parameter does not contain information; 
therefore, pass a NULL pointer for the input_dcb parameter. 


F tetr an sferou t_dc b 

struct Ft_etransfer_out_dcb { 
Uint32 

struct Api_rc 

enum Ft_action_result 

struct Ft_diagnostic 

} ; 


size; 
result; 

action_result; 
*diagnostic; 
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ft_etransfer() Parameters 


ft_etransfer() 

Parameter 

Type 

Description 

connectionjd 

Mandatory 

1 nput 

Uniquely identifies a 
specific connection to the 
filestore 

return_event_name 

Mandatory 

1 nput 

If the call is asynchronous, 
uniquely identifies the 
function call; if the call is 
synchronous, the value is 
zero 

input_dcb 

Optional 1 nput 

Contains no information; 
pass a N U L L poi nter 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the 
inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc 
contai ni ng the outcome of 
the operation: result_code 
and vendor_code 
(H P-UX—specific error) 

inout_dcb- 
>action_result 

Output 

Specifies the overall success 
or fai 1 ure of the request 

inout_dcb->diagnostic 

Output 

Provides 1 SO-specific error 
information 


ft cancel () 


#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_cancel (connection_id, return_event_name, input_dcb, 
inout_dcb) 

Connection_id connection_id; 

Local_event_name return_event_name; 

struct Ft_cancel_in_dcb *input_dcb; 

struct Ft_cancel_out_dcb **inout_dcb; 
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Useft_cancel() to prematurely terminate the transferring of data. Using 
ft_cancel() does not abort the entire connection (as does ft_abort()). An 
exampl e of using ft_cancel() could be when you are reading data from one 
FTAM file and writing to another, and you encounter an error when 
writing the data. You may want to cancel reading data from the FTAM 
file. 

Call ft_cancel() after ft_read() or ft_write(), rather than calling 
ft_etransfer(). 

• If you are reading a file, you will not lose data. If you are writing to a 
file, you may or may not lose the data you wrote. 

• I nvoki ng ft_cancel () i n the Data Transfer regi me moves you back to 
the File Open regime. 

Ftcancelindcb 

struct Ft_cancel_in_dcb { 

enum Ft_action_result 
struct Ft_diagnostic 

}; 


Ftcanceloutdcb 

struct Ft_cancel_out_dcb { 
Uint32 

struct Api_rc 

enum Ft_action_result 

struct Ft_diagnostic 

} ; 


action_result; 
*diagnostic; 


size; 
result; 

action_resuit; 
*diagnostic; 
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ftcancelQ Parameters 


ft_cancel() 

Parameter 

Type 

Description 

connection_id 

M andatory 

1 nput 

Uniquely identifies a 
specific connection to the 
filestore 

return_event_name 

M andatory 

1 nput 

If the call is asynchronous, 
uniquely identifies the 
function call; if the call is 
synchronous, the value is 0 
(zero) 

input_dcb- 

>action_result 

M andatory 

1 nput 

1 ndi cates failure of the data 
transfer; must be set to 

FT AR PERMANENT ER 
ROR 

i n put_dcb- >di agnost i c 

Optional 1 nput 

1 SO-specific error 
information; HP-UX 
responders accept, but 
ignore, this value 

inout_dcb->size 

M andatory 
input if using 
inout_dcb 

Size (in Octets) of the 
inout_dcb structure and 
data 

inout_dcb->result 

Output 

Poi nter to the struct Api_rc 
contai ni ng the outcome of 
the operation: result_code 
and vendor_code 
(H P-UX—specific error) 

inout_dcb- 
>action_result 

Output 

Specifies the overall success 
or fai 1 ure of the request 

i nout_dcb->diagnostic 

Output 

Provides 1 SO-specific error 
information 
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ftrcancelQ 


#include %</opt/ftam/include/map.h> 

#include %</opt/ftam/include/mapftam.h> 

Return_code 

ft_rcancel (connection_id, return_event_name, input_dcb, 
inout_dcb) 

Connection_id connection_id; 

Local_event_name return_event_name; 

struct Ft_rcancel_in_dcb *input_dcb; 

struct Ft_rcancel_out_dcb **inout_dcb; 


If an error occurs during a data transfer, the responder sends you a 
cancel indication. To acknowledge you received this indication, call 
ft_rcancel(). A cancel indication returns either as an 

• inout_dcb->result.return_codeof 

FTE 175_FCANCEL_l N_RECEI VED on ft_sdata() or 

• as an inout_dcb->data_unit.structure_id of FT_CANCEL_I ND on 
ft_rdata(). 

If you do not send ft_rcancel(), you receive a protocol error which results 
in an abort. 

• I nvoking ft_rcancel() in the Data Transfer regime moves you back to 
the File Open regime. 

F trcancel _i ndcb 

struct Ft_rcancel_in_dcb { 

enum Ft_action_result 
struct Ft_diagnostic 

}; 


action_result; 
*diagnostic; 


Ftrcanceloutdcb 

struct Ft_rcancel_out_dcb { 

Uint32 size; 

struct Api_rc result; 

}; 
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ftrcancelQ Parameters 


ft_rcancel() 

Parameter 

Type 

Description 

connection_id 

Mandatory 

1 nput 

Uniquely identifies a 
specific connection to the 
filestore 

return_event_name 

Mandatory 

1 nput 

1 f the cal 1 is asynchronous, 
uniquely identifies the 
function call; if the call is 
synchronous, the value is 
zero 

input_dcb-> 

action_result 

Mandatory 

1 nput 

1 ndicates fai 1 ure of the data 
transfer; set to the 
action_result received from 
the cancel indication 

input_dcb->di agnostic 

Optional 

1 nput 

1 SO-specific error 
information; set to the 
diagnostic received from the 
cancel indication 

inout_dcb->size 

Mandatory 
input if using 
inout_dcb 

Size (in Octets) of the 
i nout_dcb structure and data 

inout_dcb->result 

Output 

Pointer to the struct Api_rc 
contai ni ng the outcome of 
the operation: result_code 
and vendor_code 
(H P-UX—specific error) 
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Before writing programs to detect errors, you should be familiar with the 
following concepts. (Refer to the "HP-UX FTAM Overview" and "Using 
FTAM " chapters for descriptions of these concepts.) 
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• Synchronous and Asynchronous calls 

• Context Free and Context Sensitive calls 

• H igh and Low level services (H LS and LLS) 

You should also understand the various failure types and the differences 
in errors occurring on synchronous versus asynchronous calls. This 
chapter covers both of these topics. 
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Chapter Overview 

This chapter first describes general troubleshooting procedures for 
FTAM. The remaining sections explain the actions listed in these general 
guidelines. The specific topics are as follows. 

• General Approach ^Troubleshooting FTAM 

• I nterpreting Errors 

• Function Return Values 

• Output Errors 

• MAP 3.0 FTAM Errors 

• hiP-UX-specific Errors 

• FTAM Protocol Machine(FPM) and Virtual Filestore (VFS) Errors 

• action_result 

• state_result 

• diagnostic 

• Example Program Checking for Errors 

• Logging Errors 

• Using API Tracing 

NOTE Refer to the FI P FTAM/9000 Reference Manual for lists of errors, their 

probable causes, and possible recovery actions. 
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General Approach to Troubleshooting 
FTAM 

To write a supportable program, you must check for errors. If you receive 
an error, use the following guidelines and Figure 9-1 to help you resolve 
the problem. 

1. Check all error codes (return_codes, vendor_codes, diagnostics). The 
"I nterpreti ng E rrors" secti on descri bes the val ues you i nterpret. 

2. Useft_gperror() to format errors into printable character strings and 
to obtain log instances. 

3. Correct the errors as indicated by these values. If needed, look up the 
error code i n the H P FTAM/9000 Reference Manual todetermine 
probable causes and corrective actions. 

4. If the error still occurs, check the log file (described in the "Logging 
Errors" section) for error information, such as error codes, program 
status, and log instance. If you do not have a log instance, find the 
logged error by searching on the error string in the log file and by 
searching on the relative time when the error occurred. 

5. If the error still occurs, record the foil owing error information and 
refer to the OSI Planning and Troubleshooting Guide for corrective 
actions. 

• Specific function call that failed 

• I nput parameters passed to the function 

• Function return value 

• inout_dcb->result.return_code 

• inout_dcb->result.vendor_code 

• inout_dcb->diagnostic 

• return_string returned by ft_gperror() 

• vendor_string returned by ft_gperror() 

• Log i nstance (upper 16 bits of the vendor_code) 
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Figure 9-1 General Approach to Troubleshooting FTAM 
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Interpreting Errors 

Your program detects errors in two locations. 

• Function Return Values (includes Event Management (EM) values) 

• Output parameters 

Function Return Values 

Function return values indicate whether an error occurred. 

• Function return values return in the program as integers. 

• These values may occur because of errors on previous calls. For 
example, if the first call within a group fails, thereafter every function 
within the group fails. 

• ThevaluezeroindicatesSUCCESS. 

Refer to the FI P FTAM/ 9000 Reference Manual for a list of function 
return values. 

Synchronous Calls 


Asynchronous 

Calls 


• If the value is SUCCESS, the request 
successfully passed to the application 
interface, ftamjnit, and responder, and 
returned back to the user program. 

• If the value indicates an error, the 
application interface, ftamjnit, or responder 
detected the error. 

• If the value is SUCCESS, the request 
successfully passed from the application 
i nterface to ftamj nit. 

• If the value indicates an error, the 
application interface detected the error. 
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Output E rrors 

Information returned in the inout_dcb fields may be defined by MAP 3.0 
FTAM, HP-UX FTAM, FTAM Protocol Machine (FPM), ortheVFS. 


This Error 

MAP 3.0 FTAM error 
HP-UX FTAM specific error 
FPM or VFS error 


Returns As 

result.return_code 

result.vendor_code 

action_result 

state_result 

diagnostic 


MAP 3.0 FTAM Errors 

Errors detected by the interface, an ftamjnit, or an FTAM responder are 
mapped to MAP 3.0 FTAM errors and returned to the user program. 

• The inout_dcb->result.return_code contains the MAP 3.0 FTAM error. 

• To receive a printable character string and a log instance, call 
ft_gperror(). 

Refer to the H P FTAM/ 9000 Reference Manual for a list of MAP 3.0 
FTAM errors and possible corrective actions. 
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• The MAP 3.0 FTAM result.return_code is 
always the same as the function return value. 

• If result.return_code is SUCCESS, the 
request successfully passed to the application 
interface, ftamjnit, and responder, and 
returned back to the user program. 

• If result.return_code indicates an error, the 
application interface, ftamjnit, or responder 
detected the error. 

• The em_wait() function returns a val ue for a 
specific event. If an error occurs in ftamjnit 
or the responder, the function return value of 
em_wait() indicates SUCCESS and the 
result.return_code of the original function 
identifies the error. 

• The inout_dcb pointer and structure are not 
valid until theem_wait() request returns 
successfully. If you do not call em_wait(), you 
will not know if the request completed. 

HP-UX-Specific Errors 

Errors detected by the interface, an ftamjnit, or an FTAM responder 
may contain HP-UX FTAM implementation-specific error information 
that is returned to the user program. The vendor_code contains both 
HP-UX—specific error information (lower 16 bits) and the log instance 
(upper 16 bits). 

• The inout_dcb->result.vendor_code contains the vendor errors; 
however, not all errors returning in inout_dcb->result have an 
accompanying vendor_code. 

• To receive a printable character string and a log instance, call 
ft_gperror(). 

• The vendor_codefrequently provides additional information when 
errors return on HLCF functions. 

Many vendor_codes indicate internal errors that require H P support 
assistance. Refer first, however, to the HP FTAM/ 9000 Reference 
Manual for a list of H P-UX—specific errors and possible corrective 
actions. 


Synchronous 

Calls 


Asynchronous 

Calls 
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FPM and VFS Errors 

FPM errors are generated in the FTAM protocol machine and VFS errors 
are generated in the Virtual Filestore. Both FPM or VFS errors return 
an action_result, and may optionally return a state_result or diagnostic. 

action_result. The action_result reflects the overall success or failure 
of the request and returns as either FT_AR_SUCCESS or 
FT_AR_PERMAN ENT_ERROR, respectfully. 

enum Ft_action_result { 

FT_AR_SUCCESS=0, 

FT_AR_TRANSIENT_ERR0R=1, 

FT_AR_PERMANENT_ERR0R=2 

} ; 

state result. Thestate_result indicates whether the FPM madethe 
regime change and returns as either FT_SR_SUCCESS or 
FT_SR_FAI LURE. 

enum Ft_state_result { 

FT_SR_SUCCESS=0, 

FT_SR_FAILURE=1 

}; 

diagnostic. The diagnostic reflects the information defined by I SO/I S 
8571. The diagnostic may be informational only or it may be error 
information that elaborates on the action_result. (Refer to Figure 9-2.) 

• The diagnostic->error_id is the error identifier that returns in the 
Ft_diagnostic structure. 

• For a character string describing the error, check the 
diagnostic->further_details field for additional information. 

• Multiple I SO errors may be represented by a single MAP error; more 
than one diagnostic may return. 

• Multiple FPM errors may occur on one cal I and are represented by a 
linked list of inout_dcb->diagnostic structures. 

Refer to the H P FTAM/ 9000 Reference Manual for a list of 
di agnostic->error_ids. 
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Figure 9-2 


diagnostic { 


struct Ft_diagnostic 

*next; 

enum Ft_diag_type 

diag_type; 

Uint16 

error_id; 

enum Ft_entity_ref 

error_observer; 

enum Ft_entity_ref 

error_source; 

Uintl6 

suggested_delay; 

char 

*further_details 


i nout_dcb->diagnostic 


struct inout deb 



diagnostic 

Field 


Description 


next Pointer to another Ft_diagnostic structure or NULL 

to indicate end of linked list; refer to mapftam.h. 

diag_type A description of the error type; refer to mapftam.h. 

HP-UX responders do not return the 
FT TRANSIENT value. 
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enum FT_diag_type { 

FT_INFORMATIVE = 0, 
FT_TRANSIENT = 1, 
FT_PERMANENT = 2 


errorjd The actual error as defined by I SO/I S 8571. Refer to 

the HP FTAM/9000 Reference Manual for a list of 
theerrorjds, causes, and corrective actions. 

error_observer The entity that detects the error; refer to mapftam.h. 


enum FT_entity_ref { 

FT_NOT_CATEGORIZED = 0, 
FT_INITIATING_FILE_SERVICE_USER = 1, 
FT_INITIATING_FILE_PROTOCOL_MACHINE = 2, 
FT_SERVICE_SUPPORTING_FILE_PROTOCOL_MACHINE = 3, 
FT_RESPONDING_FILE_PROTOCOL_MACHINE = 4, 
FT_RESPONDING_FILE_SERVICE_USER = 5 


} ; 


diagnostic 

Field 


Description 


error_source Where the error is perceived to have originated. 


enum Ft_entity_ref { 

FT_NOT_CATEGORIZED = 0, 

FT_INITIATING_FILE_SERVICE_USER = 1, 

FT_INITIATING_FILE_PROTOCOL_MACHINE = 2, 

FT_SERVICE_SUPPORTING_FILE_PROTOCOL_MACHINE = 3, 

FT_RESPONDING_FILE_PROTOCOL_MACHINE = 4, 

FT_RESPONDING_FILE_SERVICE_USER = 5 

}; 


suggested_delay Recommended delay before cal ling the fundi on 
again; useful only for transient errors. HP-UX 
responders do not return suggested_delay 
information. 

further_details Additional information that may help you better 
understand the diagnostic->error_id; refer to 
mapftam.h. 
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Example Program Checking for Errors 

This example checks the result.return_code, result.vendor_code, and 
Ft_diagnostic structures. This example also uses printfO statements to 
print the results. 


#include 

#include 

finclude 

/* 

★ 

■k ~k 


%</opt/ftam/include/map.h> 
%</opt/ftam/include/mapftam.h> 
%<stdio.h> 


error_handler 


DESCRIPTION: 

This routine is an example of handling failures experienced 
during the FTAM functions. This routine will display the 
error messages. 


** PARAMETERS: 
** INPUT: 

** result : 

** diag : 


the MAP and HP error information 
the ISO error information 


*/ 

void 

error_handler(result, diag) 

Api_rc result; 

struct Ft_diagnostic *diag; 


Return_code 

Api_rc 

Octet 

Octet 

struct Ft_diagnostic 
/* 

** Initialize 
*/ 

return_string = 
vendor_string = 


res; 

outcome; 
*return_string; 
*vendor_string; 
*ft_diag = NULL; 

variables. 

NULL; 

NULL; 


344 


Chapter 9 



Handling Errors 

Example Program Checking for Errors 


** Call ft_gperror to get the printable strings for 
** the return_code and vendor_code. Print the 
** strings returned from ft_gperror. 

*/ 

res = ft_gperror(& result, & return_string, & vendor_string, & 
outcome); 

if (res == SUCCESS) { 

if (return_string != NULL) { 

(void)printf("FTAM failure: return_code = %s\n", return_string); 
res = ft_fdmemory(return_string, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, ft_diag) ; 

} 

/* 

** Print the vendor_code if it exists. 

*/ 

if (vendor_string != NULL) { 

(void)printf("FTAM failure: vendor_code = %s\n", vendor_string); 
res = ft_fdmemory(vendor_string, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, ft_diag); 

} 


/* 

** Traverse the diagnostic list and print the further_details 

strings. 

*/ 

while(diag != NULL) { 

(void)printf("FTAM failure: diagnostic number = %d\n", 
diag->error_id) ; 

if(diag->further_details != NULL) 

(void)printf("FTAM failure: diagnostic = %s\n", 
diag->further_details) ; 
diag = diag->next; 

} 

exit (1); 

} 
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Logging Errors 

All errors return both in your programs and in the log files. When any of 
the OSI layers have an error, the error propagates up the stack, creating 
an error at each layer. The number that identifies the error is called a log 
instance. For example, if an error occurs at the Presentation layer, a 
related error also occurs at the Application layer. The same log instance 
occurs at least twice, identifying the related errors at both layers. 

If you are unableto resolve errors returned in the user program, refer to 
the logfilefor additional error information, such as program status. This 
information may help you resolve the error or you may use it when 
calling an HP support representative or referencing the OSI Planning 
and Troubleshooting Guide. 

Log classes include DISASTER, ERROR, WARNING, and 
INFORMATIVE cases. 
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Example Program Containing Error 
Information 

Given a vendor_code, the foil owing example creates a log filter file 
(/tmp/input_file) that the troubleshooting tool osidump usestocheck for 
errors (via log instances in the log file). The file created records a time 
period (during which theerror isassumed to have occurred), thelogclass 
to filter on, and the log instance. Following the program is sample 
output. 


This routine 
command. The 
and time_to. 
log instance 
the instance 


creates a input FORMAT file for use by the "osidump" 
FORMAT file is created with two time lines, time_from 
A log class of ERROR is used to search on, and if a 
is present (upper 16 bits of the vendor code), then 
will also be added to the filter file. 


*/ 

search_log(vcode) 
int vcode; 


FILE *fp, *fopen(); 
long now, time(); 
int log_instance; 

struct tm *localtime(); 
struct tm *clock; 
extern long timezone; 

/* open a /tmp file to store the FORMAT data */ 
if ((fp = fopen("/tmp/input_file", "w")) == NULL) { 
fprintf(stderr, "fopen error\n") ; 
exit(1) ; 

} 

/* get current time */ 
now = time ((long *) 0); 
clock = localtime(& now); 

/* get the upper 16 bits of the vendor_code */ 
log_instance = vcode >> 16; 

/* write log filter file */ 

fprintf(fp, "FORMATTER\tfilter\ttime_from\t"); 
if (clock->tm_min > 2) 

fprintf(fp, "%d:%02d:%02d\t", clock->tm_hour, 
clock->tm_min - 3, clock->tm_sec); 

else 

fprintf(fp, "%d:%02d:%02d\t", (clock->tm_hour + 23)%24, 
(clock->tm_min + 57)%60, clock->tm_sec); 


Chapter 9 


347 



Handling Errors 

Example Program Containing Error Information 


fprintf(fp, "%d/%d/%d\n", clock->tm_mon+l, 
clock->tm_mday, clock->tm_year); 
fprintf (fp, "FORMATTER\tfilter\ttime_to \t"); 
fprintf(fp, "%d:%02d:%02d\t", clock->tm_hour, 
clock->tm_min, clock->tm_sec); 
fprintf(fp, "%d/%d/%d\n", clock->tm_mon+l, 
clock->tm_mday, clock->tm_year); 

/* set filter "class" to ERROR */ 

fprintf(fp, "FORMATTER\tfilter\tclass \tERROR\n"); 

if (log_instance) /* log instance present */ 

fprintf(fp, "FORMATTER\tfilter\tlog_instance\t%d\n", 
log_instance) ; 

fclose(fp); 

/* Run osidump with the input FORMAT file just created */ 
system("osidump -c /tmp/input_file > /tmp/log_file"); 


The foil owing text is an example of what you might find in 
/tmp/input_file. 


FORMATTER 

FORMATTER 

FORMATTER 

FORMATTER 


filter time_from 
filter time_to 
filter class 
filter log_instance 


14:02:16 

14:05:16 

ERROR 

9284 


4/13/89 

4/13/89 
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Using API Tracing 

API tracing allows you to get detailed information about your program's 
interactions with the HP FTAM API without your having to access your 
source code. It provides the return value of each API call made by your 
program as wel I as the i nput parameters to each cal I. 

API Tracing Variables 

HP FTAM API tracing is controlled by the following three global 
variables. 

• ft_trace indicates the trace level to be used. The default value of 
ft_trace is 0, which indicates no tracing, but the value may instead be 
defined in the%<api_trace.h>file as either of the foil owing: 

• API_TR_ENTRY_EXIT — procedure entry and exit are traced. No 
parameter information is displayed. This is useful if you are 
interested only in seeing what FTAM calls your program is 
making. This value is defined as 0x1. 

• API_TR_INPUT — input parameters to the FTAM functions, as 
well as procedure entry and exit, are traced. This is useful is you 
want to verify that FTAM is actually receiving the values you 
expect. This value is defined as 0x2. 

• ft_trace_fp is a file pointer that is used to write the trace records. The 
default is stderr. You can redirect the trace information to be saved to 
a specific file, and then usefopen to open the file. 

• ft_trace_max_udata indicates the maximum amount of user data (in 
bytes) to be displayed during tracing. The default is 16. 

Enabling API Tracing 

The foil owing steps show how to enable API tracing in your program. 

1. To include the appropriate definitions, add lines similar to the 
foil owing to your program: 

#include %<api_trace.h> 
extern int ft_trace; 
extern FILE *ft_trace_fp; 
extern int ft_trace_max_udata 
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2. Within your program, enable tracing by changing the value of the 
ft_trace variable from Otoeither API_TR_ENTRY_EXIT or 
API_TR_I NPUT. (The "Resolving FTAM Problems"chapter in the HP 
FTAM/ 9000 User's Guide provides information on enabling and 
disabling API tracing during an interactive FTAM session.) 

3. If you want the trace output to be written to a file, redirect the trace 
output from stderr as follows. 

ft_trace_fp = fopen("/tmp/my_ft_trace","a"); 

4. If you want more than the first 16 bytes of data to be displayed, 

increase the value of the ft_trace_max_udata variable. For example: 

ft_trace_max_udata = 256 

5. If you want API trad ng to be a runtime option, use the-t option 
shown in the foil owing sample code, and enter program_name-t at 
runtime. 

The foil owing example shows how to use the variables. 

#include %<api_trace.h> 
extern int ft_trace; 
extern FILE *ft_trace_fp; 
extern int ft_trace_max_udata; 


main (argc,argv) 

Int argc; 
char **argv; 

{ 

/* To run, enter "program name -t" to enable tracing*/ 
/* Check if tracing needs to be turned on */ 

if ((argc ==2) & & (strcmp(argv{1}, "-t") == 0)) 

{ 

/* Turn tracing on, create trace file */ 
ft_trace = API_TR_INPUT; 

ft_trace_fp = fopen("/tmp/my_trace_file", "a"); 
ft_trace_max_udata = 256 

else 

ft_trace = 0 /*To be safe, always initialize it*/ 

/*Then do whatever you have to do*/ 

} 


I nterpreting theTrace File 

Every time a routine is entered and exited, the time (in hh:mm:ss 
format) and the name of the cal I are shown. First the-> arrow indicates 
the beginning of the cal I, then the input parameters are shown, and then 
the%<- arrow indicates the exit. The number following the%<- arrow is 
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the integer value of the return code for that call. A value of 0 indicates 
that there were no errors. If an integer other than 0 is returned, refer to 
the/opt/ftam/includei/mapftam.h file to determine which return code 
corresponds to the integer, and then refer to the "FTAM return_codes” 
chapter of the H P FTAM/9000 Reference Manual for the cause of the 
return code and corrective actions you can take. 

The following is an example trace file for an H P FTAM session. 


Tue Sep 1 08:55:14 1992 ->ft_aeactivation() 
my_ae_name = 0x5a718 
return_event_name = 0 
input_dcb->authentication = NULL 

input_dcb->my ae_title_option = User_object_id_option 
input_dcb->my ae_title = 0x5a908 
Tue Sep 1 08:55:15 1992 %<-ft_aeactivation() = 0 
Tue Sep 1 08:55:15 1992 ->ft_connect() 
ae_label = 0x202c0006 
return_even_name = 0 
called_ae_name = 0x5a9bc 

input_dcb->called_presentation_address = 0x0 
input_dcb->called_ae_title_option = User_object_id_option 
input_dcb->called_ae_title = 0x5acl4 
input_dcb->called_ae_invoke_id = 0x80000000 
input_dcb->called_ap_invoke_id = 0x80000000 
input_dcb->number_of_retry = 0 
input_dcb->delay_between_retry = 0 
input_dcb->connection_resource_wait_timer = 0 
input_dcb->context_name =10 8571 1 1 
input_dcb->connect_in_info.service_class: 

FT_SC_TRANSFER 
F T_S C_T RAN S F E R_AN D_MGMT 
input_dcb->connect_in_info.functional_units: 

FT_FU_READ 
F T_F U_WR IT E 

input_dcb->connect_in_info.attribute_groups 
F T_AG_S TORAGE 
FT_AG_PRIVATE 

input_dcb->connect_in_info.quality_of_service = FT_NO_RECOVERY 
input_dcb->connect_in_info.contents_type_list: 0x5ac7 4 

input_dcb->connect_in_info.contents_type_list.contents_type.connects_form = 
FT_DOCUMENT_TYPE 

contents_type->contents_info.document.name.length = 5 
contents_type->contents_info.document.name.element: 1 0 8571 5 3 
input_dcb->connect_in_info.initiator_identity = "root" 
input_dcb->connect_in_info.account = "account" 
input_dcb->connect_in_info.file_store_pw = "ftam" 

Tue Sep 1 08:55:17 1992 %<-ft_connect() = 0 
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Tue Sep 1 08:55:18 1992 ->ft_open() 
connection_id = 65535 
processing_mode: 

FT_PM_READ 
FT_PM_RE PLACE 
FT_PM_EXTEND 
F T_P M_E RASE 

contents_type->contents_info.document.name.length = 5 
contents_type->contents_info.document.name.element: 1 
return_event_name = 0 

input_dcb->concurrency_control = NULL 
Tue Sep 1 08:55:18 1992 %<-ft_open() = 0 
Tue Sep 1 08:55:18 1992 ->ft_read() 
connection_id = 65536 

fadu_identity->fadu_form = FT_FADU_LOCATION 
fadu_identity->fadu_info.fadu_location = FT_FIRST 
access_context = UNSTRUCTURED_ALL_DATA_UNITS 
return_event_name = 0 
Tue Sep 1 08:55:18 1992 %<-ft_read() = 0 
Tue Sep 1 08:55:19 1992 ->ft_close() 
connection_id = 65535 
return_event_name = 2 
Tue Sep 1 08:55:19 1992 %<-ft_close() = 0 


0 8571 5 3 
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Former Introduction ... need to change 

You can learn from the code examples in this chapter, and pattern your 
applications after them. The examples are in the following order. 


UsingHLCF Functions This routine synchronously callsthe HLCF functions 

Example ft_fcopy(), ft_fcattributes(), and ft_fdelete(). Additionally, 

the routine uses ft_dfdcb() to free dynamically allocated 
data control blocks (DCBs). 


Managing FTAM Connections This routine activates ftamjnit and synchronously 
Example establishes a connection to a responder. The routine then 

releases the connection and deactivates the ftam init. 


Using LLCS Functions This routine transfers a source filetoa destination 

Example directory using LLCS functions. 


Setting Ae_dir_dn and This routine sets the directory distinguished name and 

P_address Utility Example presentation address for the first three examples. 


Checking for Errors Example This routine checks the function return value, 

result.return_code, result.vendor_code, and diagnostic for 
the first three examples. 


Common Code Example This routine contains global definitions and common code 

used by the first three examples. 


NOTE For an on-l ine copy of the example that sets the Ae_dir_name and 

P_address, refer to/opt/osi/lib/demos. For on-line copies of all the other 
examples, refer to/opt/ftam/demos. (Seethe README files in both 
directories.) 


Additionally, you can refer totheon-linefile/opt/ftam/demos/makefilefor 
an example Makefile used to compile the example programs. 
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Using HLCF Functions Example 

This example program synchronously calls the high level context free 
functions ft_fcopy(), ft fcattributesO, ft_fdelete(). Additionally, the 
program uses ft_dfdcb[) to free dynamic memory. Refer to the fol lowi ng 
three sections for associated routines: "Setting Ae_dir name and P 
address Utility Example," "Checkingfor Errors Example," and "Common 
Code Example." 


#include 
#include 
#include 
tinclude 
main () 

/* 
k k 

k k 


%</opt/ftam/include/map.h> 

%</opt/ftam/include/mapftam.h> 
"ftm_globs.h" 

%<stdio.h> 


ftm_hlcopy 


k k 
k k 
k k 
k k 

* / 


DESCRIPTION: 

This example program uses high level, context free functions 
synchronously. This program copies a file, changes the 
attributes of the destination file and deletes the source file. 


Ae_label 

Ae_dir_name 

Ft_filename 

Ae_dir_name 

Ft_filename 

Local_event_name 

struct Ft_fcopy_in_dcb 

struct Ft_fcopy_out_dcb 

struct Ft_fcattributes_in_dcb 

struct Ft_fcattributes_out_dcb 

struct Ft_fdelete_in_dcb 

struct Ft_fdelete_out_dcb 

Return_code 

Api_rc 

struct Ft_diagnostic 

(void)printf(”ftm_fcopy: start 
/* 


ae_label; 
source_dirname; 
source_filename; 
destination_dirname; 
destination_filename; 
return_event_name; 

*fco_input_dcb; 

*fco_inout_dcb; 

*fca_input_dcb; 

*fca_inout_dcb; 

*fde_input_dcb; 
*fde_inout_dcb; 
res; 

outcome; 

*diag = NULL; 
ing\n"); 


** Copy the source file to the destination directory. 

k k 


** Get the parameters for ft_fcopy. 

** Call ft_fcopy and verify the outcome. 

k / 

(void)printf("Copying the source file to the destination directory ...\n"); 

fco_parm_in( & source_dirname, & source_filename, 

& destination_dirname, & destination_filename, 

& ae_label, & return_event_name, & fco_input_dcb, 

& fco_inout_dcb ); 

res = ft_fcopy(source_dirname, source_filename, destination_dirname, 
destination_filename, & ae_label, 

return_event_name, fco_input_dcb, & fco_inout_dcb); 

if (res != SUCCESS) 

error_handler(fco_inout_dcb->result, fco_inout_dcb->diagnostic); 
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7* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)fco_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 
res = ft_dfdcb((Octet *)fco_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Change the attributes of the destination file. 

■k 

** Get the parameters for ft_fcattributes. 

** Call ft_fcattributes and verify the outcome. 

*/ 

(void)printf("Changing attributes of the destination file...\n"); 
fca_parm_in( & destination_dirname, & destination_filename, 

& ae_label, & return_event_name, & fca_input_dcb, 

& fca_inout_dcb ); 

res = ft_fcattributes(destination_dirname, destination_filename, 

& ae_label, return_event_name, fca_input_dcb, 

& fca_inout_dcb) ; 

if (res != SUCCESS) 

error_handler(fca_inout_dcb->result, fca_inout_dcb->diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)fca_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)fca_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Delete the source file. 

■k 

** Get the parameters for ft_fdelete. 

** Call ft_fdelete and verify the outcome. 

*/ 

(void)printf("Deleting the source file...\n"); 
fde_parm_in( & source_dirname, & source_filename, 

& ae_label, & return_event_name, & fde_input_dcb, 

& fde_inout_dcb ); 

res = ft_fdelete(source_dirname, source_filename, & ae_label, 

return_event_name, fde_input_dcb, & fde_inout_dcb); 
if (res != SUCCESS) 

error_handler(fde_inout_dcb->result, fde_inout_dcb->diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdeb((Octet *)fde_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdeb((Octet *)fde_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(void)printf("ftm_hlcopy: finished\n"); 
return(SUCCESS); 
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Managing FTAM Connections Example 

This example uses theft_aeactivation(), ft_connect(), ft_rrequest(), 
ft_aedeactivation(), and ft_dfdcb() functions. Refer to the foil owing 
sections for associated routines: "Setting Ae_dir_dn and P_address 
Utility Example," "Checking for Errors Example," and "Common Code 
Example." 


#include 
#include 
finclude 
#include 
main () 

/* 

•k k 

k k 


%</opt/ftam/include/map.h> 

%</opt/ftam/include/mapftarn.h> 
"ftm_globs.h" 

%<stdio.h> 


ftm_connect 


DESCRIPTION: 

This example program illustrates how to establish 
a connection with an active "ftam_init" synchronously. 
This program also releases the connection and deactivates 
"ftam_init". 


k k 
*/ 


Ae_label 

Connection_id 

Ae_dir_name 

Ae_d i r_n arne 

Local_event_name 

struct Ft_aeactivate_in_dcb 

struct Ft_connect_in_dcb 

struct Ft_relreq_in_dcb 

struct Ft_output 

struct Ft_connect_out_dcb 

struct Ft_relreq_out_dcb 

struct Ft_output 

Return_code 

Api_rc 

struct Ft_diagnostic 


ae_label; 

connection_id; 

my_ae_name; 

c a11e d_ae_name; 

return_event_name; 

*aea_input_dcb; 

*con_input_dcb; 

*rre_input_dcb; 

*aea_inout_dcb; 

*con_inout_dcb; 

*rre_inout_dcb; 

*aed_inout_dcb; 

res; 

outcome; 

"diag = NULL; 


(void)printf(”ftm_connect: starting\n"); 
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/* 

** Activate "ftam_init". 

•k 

** Get the parameters for ft_aeactivation. 

** Call ft_aeactivation and verify the outcome. 

*/ 

(void)printf("Activating ftam_init...\n"); 

aea_parm_in( & my_ae_name, & return_event_name, & aea_input_dcb, 

& aea_inout_dcb, & ae_label ) ; 

res = ft_aeactivation(my_ae_name, return_event_name, aea_input_dcb, 

& aea_inout_dcb, & ae_label); 

if (res != SUCCESS) 

error_handler(aea_inout_dcb->result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)aea_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Establish a connection with the responder. 

■k ~k 


** Get the parameters for ft_connect. 

** Call ft_connect and verify the outcome. 

*/ 

(void)printf("Establishing a connection with the responder ...\n"); 
con_parm_in( & return_event_name, & called_ae_name, & con_input_dcb, 

& con_inout_dcb, & connection_id ) ; 
res = ft_connect(ae_label, return_event_name, called_ae_name, 

con_input_dcb, & con_inout_dcb, & connection_id); 
if (res != SUCCESS) 

error_handler(con_inout_dcb->result, 

con_inout_dcb->connect_out_info->diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)con_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)con_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Release the connection with the responder. 

~k 

** Get the parameters for ft_rrequest. 

** Call ft_rrequest and verify the outcome. 

*/ 

(void)printf("Releasing the connection with the responder...\n"); 
rre_parm_in( & return_event_name, & rre_input_dcb, & rre_inout_dcb ); 
res = ft_rrequest(connection_id, return_event_name, rre_input_dcb, 

& rre_inout_dcb) ; 

if (res != SUCCESS) 

error_handler(rre_inout_dcb->result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rre_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 


358 


Chapter 10 



Example Programs 

Managing FTAM Connections Example 


/* 

** Deactivate "ftam_init". 

•k 

** Get the parameters for ft_aedeactivation. 

** Call ft_aedeactivation and verify the outcome. 

*/ 

(void)printf("Deactivating ftam_init...\n"); 
aed_parm_in( & return_event_name, & aed_inout_dcb ); 

res = ft_aedeactivation(ae_label, return_event_name, & aed_inout_dcb); 
if (res != SUCCESS) 

error_handler(aed_inout_dcb->result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)aed_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(void)printf("ftm_connect: finished\n"); 
return(SUCCESS); 
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Using LLCS Functions Example 

This exampl e uses the fol I owi ng functions. Refer to the fol I owi ng sections 
for associated routines: "Setting Ae_dir_dn and P_address Utility 
Example," "Checkingfor Errors Example," and "Common Code 
Example." 

• em_wait() 

• ft_aeactivation() 

• ft_dfdcb() 

• ft_connect() 

• ft_open() 

• ft_read() 

• ft_write() 

• ft_rdata() 

• ft_sdata() 

• ft_nwcleared() 

• ft_edata() 

• ft_etransfer() 

• ft_bgroup() 

• ft_select() 

• ft_rattributes() 

• ft_egroup() 

• ft_bgroup() 

• ft_create() 

• ft_open() 

• ft_egroup() 

• ft_bgroup() 

• ft_close() 

• ft_deselect() 

• ft_egroup() 
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#include 
#include 
#include 
finclude 
main () 

/* 

■k k 
:k k 


%</opt/ftam/include/map.h> 

%</opt/ftam/include/mapftam.h> 
"ftm_globs.h" 

%<stdio.h> 


ftm_llcopy 


** DESCRIPTION: 

** This example program illustrates how to transfer a file 
** using low level, context sensitive FTAM functions. This 
** program transfers the source file to the destination directory. 

k k 
* / 


Ae_dir_name 
Ae_dir_name 
Ae_label 
Local_event_name 
Connection_id 
Ft_filename 
Ft_filename 
Ft_processing_mode 
Ft_file_actions 
enum Ft_file_status 
enum Ft_access_context 
enum Ft_fadu_operation 
struct Ft_fadu_identity 
struct Ft_contents_type 
Uint16 
Uint16 

struct Ft_data_unit 
struct Ft_aeactivate_in_dcb 
struct Ft_output 
struct Ft_connect_in_dcb 
struct Ft_connect_out_dcb 
struct Ft_relreq_in_dcb 
struct Ft_relreq_out_dcb 
struct Ft_output 
char 

struct Ft_bgroup_out_dcb 
char 

struct Ft_egroup_out_dcb 
struct Ft_select_in_dcb 
struct Ft_select_out_dcb 
struct Ft_create_in_dcb 
struct Ft_create_out_dcb 
struct Ft_rattributes_in_dcb 
struct Ft_rattributes_out_dcb 
struct Ft_open_in_dcb 
struct Ft_open_out_dcb 
char 

struct Ft_read_out_dcb 
char 

struct Ft_write_out_dcb 
struct Ft_rdata_out_dcb 
struct Ft_sdata_out_dcb 
struct Ft_edata_in_dcb 
struct Ft_edata_out_dcb 


my_dirname; 
dirname; 
ae_label; 

return_event_name; 

conn_id[TWO_CONNECTIONS]; 

src_filename; 

dst_filename; 

processing_mode; 

requested_access; 

file_status; 

access_context; 

fadu_operation; 

fadu_identity; 

contents_type; 

threshold; 

des_requested; 

*data_unit; 

*aea_input_dcb; 

*aea_inout_dcb; 

* con_input_dcb; 
*con_inout_dcb; 
*rre_input_dcb; 
*rre_inout_dcb; 
*aed_inout_dcb; 
*bgr_input_dcb; 
*bgr_inout_dcb; 
*egr_input_dcb; 
*egr_inout_dcb; 

* sel_input_dcb; 
*sel_inout_dcb; 
*cre_input_dcb; 
*cre_inout_dcb; 

* rat_input_dcb; 

* rat_inout_dcb; 
*ope_input_dcb; 
*ope_inout_dcb; 

* rea_input_dcb; 
*rea_inout_dcb; 

*wri_input_dcb; 

*wri_inout_dcb; 
*rda_inout_dcb; 
*sda_inout_dcb; 

* e da_input_dcb; 
*eda_inout_dcb; 
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char 


*etr_input_dcb; 

struct 

Ft_etransfer_out_dcb 

*etr_inout_dcb; 

struct 

Ft_nwcleared_out_dcb 

*nwc_inout_dcb; 

char 


*clo_input_dcb; 

struct 

F t_c1o s e_out_dcb 

*clo_inout_dcb; 

char 


*des_input_dcb; 

struct 

Ft_deselect_out_dcb 

*des_inout_dcb; 

Em_t 


t ime ; 

Api_rc 


result; 

struct 

Ft_attributes 

attr_src; 

Return, 

_code 

res; 

Api_rc 


outcome; 

int 


i, j, index; 

Bool 


done; 

struct 

Ft_diagnostic 

*diag = NULL; 


(void)printf("ftm_llcopy: starting\n"); 
/* 

** Activate "ftam_init". 

★ 


** Get the parameters for ft_aeactivation. 

** Call ft_aeactivation and verify the outcome. 

*/ 

(void)printf("Activating ftam_init...\n"); 

aea_parm_in( & my_dirname, & return_event_name, & aea_input_dcb, 

& aea_inout_dcb, & ae_label ) ; 

res = ft_aeactivation(my_dirname, return_event_name, aea_input_dcb, 

& aea_inout_dcb, & ae_label); 

if (res != SUCCESS) 

error_handler(aea_inout_dcb->result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdeb((Octet *) aea_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Establish connections between ftam_init and the responder 
** for the source file and between ftam_init and the responder 
** for the destination file. 

★ 


** Get the parameters for ft_connect. 

** Call ft_connect and verify the outcome. 

*/ 

(void)printf("Establishing connections for the source"); 

(void)printf(" & destination files...\n"); 

con_source_parm_in( & return_event_name, & dirname, & con_input_dcb, 
& con_inout_dcb, & conn_id[0] ); 
res = ft_connect(ae_label, return_event_name, dirname, 

con_input_dcb, & con_inout_dcb, & conn_id[0]); 
if (res != SUCCESS) 

error_handler(con_inout_dcb->result, 

con_inout_dcb->connect_out_info->diagnostic); 
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7* 

** Free memory. 

*/ 

res = ft_dfdeb((Octet *)con_input_dcb, & outcome]; 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 
res = ft_dfdcb((Octet *)con_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

con_parm_in( & return_event_name, & dirname, & con_input_dcb, 

& con_inout_dcb, & conn_id[l] ); 
res = ft_connect(ae_label, ret urn_event_name, dirname, 

con_input_dcb, & con_inout_dcb, & conn_id[l]); 
if (res != SUCCESS) 

error_handler(con_inout_dcb->result, 

con_inout_dcb->connect_out_info->diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)con_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)con_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

Perform a grouped activity on the source file. 
ft_bgroup 
ft_select 
ft_rattributes 
ft_egroup 


** Get the parameters for ft_bgroup. 

** Call ft_bgroup and verify the outcome. 

*/ 

(void)printf("Selecting and reading attributes of the source file...\n"); 
bgr_parm_in( & threshold, & return_event_name, & bgr_input_dcb, 

& bgr_inout_dcb ) ; 

res — ft_bgroup(conn_id[SRC], threshold, return_event_name, 
bgr_input_dcb, & bgr_inout_dcb); 
if (res != SUCCESS) 

error_handler(bgr_inout_dcb->result, diag); 

/* 

** Get the parameters for ft_select. 

** Call ft_select and verify the outcome. 

*/ 

sel_parm_in( & src_filename, & requested_access, 

& return_event_name, & sel_input_dcb, & sel_inout_dcb ); 
res = ft_select(conn_id[SRC], src_filename, requested_access, 

return_event_name, sel_input_dcb, & sel_inout_dcb); 
if (res != SUCCESS) 

error_handler(sel_inout_dcb->result, sel_inout_dcb->diagnostic); 

/* 

** Get the parameters for ft_rattributes. 

** Call ft_rattributes and verify the outcome. 

*/ 

rat_parm_in( & return_event_name, & rat_input_dcb, & rat_inout_dcb ); 
res = ft_rattributes(conn_id[SRC], return_event_name, rat_input_dcb, 

& rat_inout_dcb); 

if (res != SUCCESS) 

error_handler(rat_inout_dcb->result, rat_inout_dcb->diagnostic); 
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7 * 

** Get the parameters for ft_egroup. 

** Call ft_egroup and verify the outcome. 

*/ 

egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); 
res = ft_egroup(conn_id[SRC], return_event_name, egr_input_dcb, 

& egr_inout_dcb) ; 
if (res != SUCCESS) 

error_handler(egr_inout_dcb->result, diag); 

/* 

** Wait on the asynchronous events in the group. 

*/ 

for (i = 1; i %<M=> 3; ++i) { 

wait_parm_in( & time, & result ); 

res = em_wait(time, & return_event_name, & result); 
if (res != SUCCESS) 

error_handler(result, diag); 
switch (return_event_name) { 

case 1: 

if (bgr_inout_dcb->result.return_code != SUCCESS) 
error_handler(bgr_inout_dcb->result, diag); 
break; 
case 2: 

if (sel_inout_dcb->result.return_code != SUCCESS) 
error_handler(sel_inout_dcb->result, 

sel_inout_dcb->diagnostic); 

break; 
case 3: 

if (rat_inout_dcb->result.return_code != SUCCESS) 
error_handler(rat_inout_dcb->result, 

rat_inout_dcb->diagnostic); 

break; 
default: 
break; 

} 


/* 

** Save the attributes of the source 
*/ 

attr_src = rat_inout_dcb->attributes; 
/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)bgr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)sel_input_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)sel_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)egr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 


f ile. 


& outcome) ; 

& outcome); 

& outcome) ; 

& outcome); 
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** Open the source file. 


** Get the parameters for ft_open. 

** Call ft_open and verify the outcome. 

*/ 

(void)printf("Opening the source file...\n"); 
ope_parm_in( & processing_mode, & contents_type, 

& return_event_name, & ope_input_dcb, & ope_inout_dcb); 
res = ft_open(conn_id[SRC] , processing_mode, contents_type, 

return_event_name, ope_input_dcb, & ope_inout_dcb); 
if (res != SUCCESS) 

error_handler(ope_inout_dcb->result, ope_inout_dcb->diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdeb((Octet *) ope_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdeb((Octet *)ope_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Perform a grouped activity on the destination file. 

** ft_bgroup 
** ft_create 

** ft_open 

** ft_egroup 
★ 


** Get the parameters for ft_bgroup. 

** Call ft_bgroup and verify the outcome. 

*/ 

(void)printf("Creating and opening the destination file...\n"); 
bgr_parm_in( & threshold, & return_event_name, & bgr_input_dcb, 

& bgr_inout_dcb ); 

res = ft_bgroup(conn_id[DST], threshold, return_event_name, 
bgr_input_dcb, & bgr_inout_dcb); 
if (res != SUCCESS) 

error_handler(bgr_inout_dcb->result, diag); 

/* 

** Get the parameters for ft_create. 

** Call ft_create and verify the outcome. 

*/ 

cre_parm_in( & dst_filename, & contents_type, 

& requested_access, & file_status, & return_event_name, 
& cre_input_dcb, & cre_inout_dcb ) ; 

/* 

** Set the attributes and contents_type of the destination file 
** to be identical with those of the source file. 

*/ 

cre_input_dcb->attributes = attr_src; 

contents_type = attr_src.values.contents_type; 

res = ft_create(conn_id[DST], dst_filename, contents_type, 

requested_access, file_status, return_event_name, 
cre_input_dcb, & cre_inout_dcb); 
if (res != SUCCESS) 

error_handler(cre_inout_dcb->result, cre_inout_dcb->diagnostic); 
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** Get the parameters for ft_open. 

** Call ft_open and verify the outcome. 

*/ 

ope_parm_in( & processing_mode, & contents_type, 

& return_event_name, & ope_input_dcb, & ope_inout_dcb ); 
contents_type = attr_src.values.contents_type; 
return_event_name = 3; 

res = ft_open(conn_id[DST], processing_mode, contents_type, 

return_event_name, ope_input_dcb, & ope_inout_dcb); 
if (res != SUCCESS) 

error_handler(ope_inout_dcb->result, ope_inout_dcb->diagnostic); 

/* 

** Get the parameters for ft_egroup. 

** Call ft_egroup and verify the outcome. 

*/ 

egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); 
res = ft_egroup(conn_id[DST], return_event_name, egr_input_dcb, 

& egr_inout_dcb); 
if (res != SUCCESS) 

error_handler(egr_inout_dcb->result, diag); 

/* 

** Wait on the asynchronous events in the group. 

*/ 

for (i = 1; i %<M=> 3; ++i) { 

wait_parm_in( & time, & result ); 

res = em_wait(time, & return_event_name, & result); 
if (res != SUCCESS) 

error_handler(result, diag); 
switch (return_event_name) { 
case 1: 

if (bgr_inout_dcb->result.return_code != SUCCESS) 
error_handler(bgr_inout_dcb->result, diag); 
break; 
case 2: 

if (cre_inout_dcb->result.return_code != SUCCESS) 
error_handler(cre_inout_dcb->result, 

cre_inout_dcb->diagnostic) ; 

break; 
case 3: 

if (ope_inout_dcb->result.return_code != SUCCESS) 
error_handler(ope_inout_dcb->result, 

ope_inout_dcb->diagnostic) ; 

break; 
default: 
break; 

} 

} 
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7* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rat_input_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 
res = ft_dfdcb((Octet *)rat_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)bgr_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)cre_input_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)cre_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)ope_input_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)ope_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)egr_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Receive data from the source file. 

★ 


outcome); 

outcome) ; 

outcome); 

outcome) ; 

outcome); 

outcome) ; 

outcome); 

outcome) ; 


** Get the parameters for ft_read. 

** Call ft_read and verify the outcome. 

*/ 

(void)printf("Reading data from the source file"); 

(void)printf("and writing data to the destination file...\n"); 
rea_parm_in( & fadu_identity, & access_context, & return_event_name, 
& rea_input_dcb, & rea_inout_dcb ); 
res = ft_read(conn_id[SRC], fadu_identity, access_context, 

return_event_name, rea_input_dcb, & rea_inout_dcb); 
if (res != SUCCESS) 

error_handler(rea_inout_dcb->result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rea_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Write to the destination file. 

★ 

** Get the parameters for ft_write. 

** Call ft_write and verify the outcome. 

*/ 

wri_parm_in( & fadu_identity , & fadu_operation, & return_event_name, 
& wri_input_dcb, & wri_inout_dcb ); 
res = ft_write(conn_id[DST], fadu_identity, fadu_operation, 

return_event_name, wri_input_dcb, & wri_inout_dcb); 
if (res != SUCCESS) 

error_handler(wri_inout_dcb->result, diag); 
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** Free memory. 

*/ 

res = ft_dfdcb((Octet *)wri_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Replace the contents of destination file with the contents 
** of source file. 


V 


done = FALSE; 
while ( ! done 

/* 
k k 


) { 


Read from the source file. 

Get the parameters for ft_rdata. 

Call ft_rdata and verify the outcome. 


k k 
k k 
k k 
*/ 

rda_parm_in(& des_requested, & return_event_name, & rda_inout_dcb) 
res = ft_rdata(conn_id[SRC], des_requested, return_event_name, 

& rda_inout_dcb); 
if (res != SUCCESS) 

error_handler(rda_inout_dcb->result, 

rda_inout_dcb->diagnostic); 


If a cancel indication returned, 
transferring data. 


stop 


/* 
k k 
k k 
k / 

data_unit = rda_inout_dcb->data_unit; 

for (index = 1; index rda_inout_dcb->des_received; 

data_unit = data_unit->next; 
if (data_unit->structure_id == FT_CANCEL_IND) { 
rda_inout_dcb ->data_unit = NULL; 
done = TRUE; 


index++) 


} 

/* 
k k 

k k 
k / 

if 


If only a data end indication was returned, 
stop transfering data. 

(rda_inout_dcb->des_received == 1 & & 

rda_inout_dcb->data_unit->structure_id == FT_DATA_END_IND) 
rda_inout_dcb ->data_unit = NULL; 
done = TRUE; 


/* 
k k 
k k 
k k 
k k 
k k 
k / 

if 


Move the data_element next pointer to the next to the 

last data_element and check for a data end indication 

on the last data_element. If one exists, set the next pointer 

to NULL so the last data_element is not written 

during the ft_sdata call. 

( ! done ) { 

data_unit = rda_inout_dcb->data_unit; 

for (index = 2; index rda_inout_dcb->des_received; index ++) 
data_unit = data_unit->next; 

if (data_unit->next->structure_id == FT_DATA_END_IND) { 
data_unit->next = NULL; 
done = TRUE; 
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** Send data to the destination file. 

k k 

** Get the parameters for ft_sdata. 

** Call ft_sdata and verify the outcome. 

*/ 

if (rda_inout_dcb ->data_unit != NULL) { 

sda_parm_in(& return_event_name, & sda_inout_dcb) ; 
res = ft_sdata(conn_id[DST], rda_inout_dcb->data_unit, 
return_event_name, & sda_inout_dcb); 
if (res != SUCCESS) { 

/* 

** If a "No connection resources" error was returned, 
** wait until the resources are free. 

*/ 

if (res == FTE008_NO_CON_RESOURCES) { 

/* 

** Get the parameters for ft_nwcleared. 

** Call ft_nwcleared and verify the outcome. 

*/ 

nwc_parm_in( & return_event_name, & nwc_inout_dcb ); 
res = ft_nwcleared(conn_id[DST] , return_event_name, 

& nwc_inout_dcb); 

if (res != SUCCESS) 

error_handler(nwc_inout_dcb->result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)nwc_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

} 

else { 

error_handler(sda_inout_dcb->result, 

sda_inout_dcb->diagnostic) ; 

} 

} 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)sda_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 


/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rda_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 


/* 

** Send a data end to the destination file. 

** Get the parameters for ft_edata. 

** Call ft_edata and verify the outcome. 

*/ 

eda_parm_in(& return_event_name, & eda_input_dcb, & eda_inout_dcb); 
res = ft_edata(conn_id[DST], return_event_name, eda_input_dcb, 

& eda_inout_dcb) ; 
if (res != SUCCESS) 

error_handler(eda_inout_dcb->result, eda_inout_dcb->diagnostic); 
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** Free memory. 

*/ 

res = ft_dfdcb((Octet *)eda_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 
res = ft_dfdcb((Octet *)eda_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** End the transfer of data to the source and destination files. 

★ 

** Get the parameters for ft_etransfer. 

** Call ft_etransfer and verify the outcome. 

*/ 

(void)printf("Ending data transfer for the source file"); 

(void)printf(" & the destination file...\n"); 
for (i = 0; i TWO_CONNECTIONS; ++i) { 

etr_parm_in( & return_event_name, & etr_input_dcb, & etr_inout_dcb ); 
res = ft_etransfer(conn_id[i], return_event_name, etr_input_dcb, 

& etr_inout_dcb); 

if (res != SUCCESS) 

error_handler(etr_inout_dcb->result, etr_inout_dcb->diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *) etr_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 


Perform a grouped activity on the source and destination files. 
ft_bgroup 
ft_close 
ft_deselect 
ft_egroup 


** Get the parameters for ft_bgroup. 

** Call ft_bgroup and verify the outcome. 

*/ 

(void)printf("Closing and deselecting the source file"); 

(void)printf(" & the destination file...\n"); 
for (i = 0; i TWO_CONNECTIONS; ++i) { 

bgr_parm_in( & threshold, & return_event_name, & bgr_input_dcb, 

& bgr_inout_dcb ); 

res = ft_bgroup(conn_id[i], threshold, return_event_name, 
bgr_input_dcb, & bgr_inout_dcb); 
if (res != SUCCESS) 

error_handler(bgr_inout_dcb->result, diag) ; 

/* 

** Get the parameters for ft_close. 

** Call ft_close and verify the outcome. 

*/ 

clo_parm_in( & return_event_name, & clo_input_dcb, & clo_inout_dcb ); 
res = ft_close(conn_id[i], return_event_name, clo_input_dcb, 

& clo_inout_dcb) ; 
if (res != SUCCESS) 

error_handler(clo_inout_dcb->result, clo_inout_dcb->diagnostic); 
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** Get the parameters for ft_deselect. 

** Call ft_deselect and verify the outcome. 

*/ 

des_parm_in( & return_event_name, & des_input_dcb, & des_inout_dcb ); 
res = ft_deselect(conn_id[i], return_event_name, des_input_dcb, 

& des_inout_dcb) ; 

if (res != SUCCESS) 

error_handler(des_inout_dcb->result, des_inout_dcb->diagnostic); 

/* 

** Get the parameters for ft_egroup. 

** Call ft_egroup and verify the outcome. 

*/ 

egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); 
res = ft_egroup(conn_id[i], return_event_name, egr_input_dcb, 

& egr_inout_dcb) ; 
if (res != SUCCESS) 

error_handler(egr_inout_dcb->result, diag); 

/* 

** Wait on the asynchronous events in the group. 

*/ 

for (j = 1; j %<M=> 3; ++j) { 

wait_parm_in( & time, & result ); 

res = em_wait(time, & return_event_name, & result); 
if (res != SUCCESS) 

error_handler(result, diag); 
switch (return_event_name) { 

case 1: 

if (bgr_inout_dcb->result.return_code != SUCCESS) 
error_handler(bgr_inout_dcb->result, diag); 
break; 
case 2: 

if (clo_inout_dcb->result.return_code != SUCCESS) 
error_handler(clo_inout_dcb->result, 

clo_inout_dcb->diagnostic); 

break; 
case 3: 

if (des_inout_dcb->result.return_code != SUCCESS) 
error_handler(des_inout_dcb->result, 

des_inout_dcb->diagnostic); 

break; 
default: 
break; 

} 


/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)bgr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)clo_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)des_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)egr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 


& outcome); 

& outcome) ; 

& outcome) ; 

& outcome); 
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** Release the connections between ftam_init and the 
** responders for the source file and the destination file. 

-k 

** Get the parameters for ft_rrequest. 

** Call ft_rrequest and verify the outcome. 

*/ 

(void)printf("Releasing connections...\n"); 
for (i = 0; i TWO_CONNECTIONS; ++i) { 

rre_parm_in( & return_event_name, & rre_input_dcb, & rre_inout_dcb ); 
res = ft_rrequest(conn_id[i], return_event_name, rre_input_dcb, 

& rre_inout_dcb); 

if (res != SUCCESS) 

error_handler(rre_inout_dcb->result, diag) ; 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rre_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 

} 

/* 

** Deactivate ftam_init 
★ 

** Get the parameters for ft_aedeactivation. 

** Call ft_aedeactivation and verify the outcome. 

*/ 

(void)printf("Deactivating ftam_init...\n"); 
aed_parm_in( & return_event_name, & aed_inout_dcb ); 

res = ft_aedeactivation(ae_label, return_event_name, & aed_inout_dcb); 
if (res != SUCCESS) 

error_handler(aed_inout_dcb->result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdeb((Octet *)aed_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(void)printf("ftm_llcopy: finished\n"); 
return(SUCCESS); 
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Setting Aedirdn and P address Utility 
Example 

This routine sets the directory distinguished name and presentation 
address for the first three examples. 


#include 

#include 

#include 

#include 

#include 

/* 


%</opt/ftam/include/map.h> 

%</opt/ftam/include/mapftam.h> 
”ftm_globs.h" 

%<stdio.h> 

%<malloc.h> 


** convert_ddn 

★ ★ 


DESCRIPTION: 

This routine scans a character string and sets up 
a n Ae_dir_name. 


■k 
■k 
■k 
•k 
■k 


■k 


PARAMETERS: 
Inputs: 
name: 


string identifying the Directory Distinguished 
Name 


** Outputs: 

** dirname: address of the pointer to the Dir_dn structure 

■k 

*/ 

void 

convert_ddn(dirname, name) 

Ae_dir_name *dirname; 

char *name; 


char 

char 

int 

Bool 


*attr; 

*value; 

i=0, j=0, k=0, index=0; 
val_flag=0, null_flag=0; 

/* 

** Determine the number of rdns. 

*/ 

while (name[j] != NULL) { 
if (name[j] == '/' ) 

++index; 

++j; 


/* 

** Malloc memory. 

*/ 

attr = (char *)malloc(strlen(name) + 1); 
value = (char *)malloc(strlen(name) + 1); 
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*dirname = (struct Dir_dn *)malloc(sizeof(struct Dir_dn)); 

(*dirname)->rdn = (struct Dir_rdn *)malloc(index*sizeof(struct Dir_rdn)); 
/* 

** Set the Ae_dir_name. 

*/ 

(*dirname)->n = index; 

/* 

** Parse the string and set up the Dir_dn structure. 

• k ~k 


** NOTE: index is set to "-1" since the string MUST start with 
** a delimiter 

*/ 

j = 0; 
index = -1; 

while ( !null_flag ) { 

/* 

** Have we reached the end of the string? 

*/ 


if (name[j] == NULL) 
null_flag = TRUE; 

/* 

** "/" is the signal for another Dir_rdn structure. 

*/ 

if ((name[j] != '/') & & ( !null_flag )) { 

/* 

** Is the attribute or the value of the attribute being parsed? 
*/ 

if (name[j] == '=') { 

val_flag = TRUE; 

} else if (val_flag) { 
value[i] = name[j] ; 

++i; 

} else { 

attr[k] = name[j]; 

++k; 

} 

++j; 


value[i] = attr[k] = '\0'; 

/* 

** Has the end of the string or the delimiter for 
** another rdn structure been reached? 

*/ 

if ((null_flag) II (name[j] == '/')) { 

if ((i != 0) & & (k != 0) ) { 

(*dirname)->rdn[index] .n = 1; 

(*dirname)->rdn[index].avas = 

(struct Dir_ava *)malloc(sizeof(struct Dir_ava)); 

(*dirname)->rdn[index].avas->attr_id.length = 1; 

(*dirname)->rdn[index].avas->attr_id.element = 

(Sint32 *)malloc(sizeof(Sint32)); 

/* 

** Set up the attr_value. 

*/ 

(*dirname)->rdn[index].avas->attr_value.pointer = 

(Octet *)malloc(i*sizeof(Octet)); 
memcpy((char *)(*dirname)->rdn[index].avas->attr_value.pointer, 
value,i); 

(*dirname)->rdn[index].avas->attr_value.length = i; 
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Set up the syntax_id to NULL. 


— For Future Use — 


(*dirname)->rdn[index].avas->syntax_id.length = 0; 

(*dirname)->rdn[index].avas->syntax_id.element = NULL; 

/* 

** Which attribute is this? Set the fourth element of the 
** attr_id accordingly. 

*/ 

if (strcmp(attr,"C") == SUCCESS) { 


/* 


C = Country 


(*dirname)->rdn[index].avas->attr_id.element[0] = 6; 
} else if (strcmp(attr,"L") == SUCCESS) { 

/* 

** L = Locality 
*/ 

(*dirname)->rdn[index].avas->attr_id.element[0] = 7; 
} else if (strcmp(attr,"0") == SUCCESS) { 


** 0 = Organization 

*/ 

(*dirname)->rdn[index].avas->attr_id.element[0] 
} else if (strcmp(attr,"OU") == SUCCESS) { 


10 ; 


V 


OU = Organizational Unit 


(‘dirname)->rdn[index].avas->attr_id.element[0] = 11; 

} else if ((strcmp(attr,"CN") == SUCCESS) I I 
(strcmp(attr,"AE") == SUCCESS) I I 
(strcmp(attr,"AP") == SUCCESS)) { 

/* 

** CN = Common Name 

** AE = Application Entity 

** AP = Application Process 

*/ 

(*dirname)->rdn[index].avas->attr_id.element[0] = 3; 

} else { 

/* 

** Unsupported attr_id. 

*/ 

(*dirname)->rdn[index].avas->attr_id.element[0] = 9999; 


/* 

** Reset counters and flags for the next rdn structure 
*/ 

i = 0; 

k = 0; 

++j; 

++index; 
val_flag = 0; 

/* 

** If there is another delimiter, move to the next 

** Dir_rdn structure and the next character in the string. 

*/ 

while (name[j] == '/') { 

++j; 

++index; 


} 
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else \ 

/* 

** Move to the next character in the string and the next 
** Dir_rdn structure in the Dir_dn structure. 

*/ 

++j; 

++index; 


/* 

★ ★ 

** convert_paddr 

★ ★ 


** DESCRIPTION: 

** This routine scans a character string and sets up 

** a P_address. 

■k 
'k 


■ k 
•k 
■ k 
■ k 
■k 
'k 
'k 


PARAMETERS: 
Inputs: 
name: 

Outputs: 
p_addr: 


string for P_address 
pointer to the P_address 


*/ 

void 

convert_paddr(p_addr, name) 

struct P_address *p_addr; 

char ‘name; 


char 

int 

Bool 


*temp; 

i=0, j=0, index=0; 
null_flag=0; 

/* 

** Malloc memory. 

*/ 

temp = (char *)malloc(strlen(name) + 1); 
p_addr->p_selector = (struct Octet_string *)malloc 
(sizeof(struct Octet_string)); 
p_addr->s_selector = (struct Octet_string *)malloc 
(sizeof(struct Octet_string)); 
p_addr->t_selector = (struct Octet_string *)malloc 
(sizeof(struct Octet_string)); 
p_addr->nsaps = (struct Octet_string *)malloc 
(8*sizeof(struct Octet_string)); 

/* 

** How many nsaps? 

*/ 

while (name[j] !— NULL) { 
if (name[j] == '.') 

++index; 

++j; 


p_addr->n_nsaps = index - 2; 
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7 * 

** Set the p_addr. 

*/ 

j = 0; 
index = 0; 

while ( !null_flag ) { 

/* 

** Has the end of the string been reached? 

* / 

if (name[j] == NULL) 
null_flag = TRUE; 

/* Parse the next field until a delimiter or the 
** end of the string has been reached. 

*/ 

if ((name[j] != & & ( !null_flag )) { 

temp[i] = name[j]; 

+ + i ; 

++j; 


4] 


/* 

** Another field has been parsed; set up the correct p_addr field. 
*/ 

if ((null_flag) I I (name[j] == '.')) { 

if (i != 0) { 

++index; 

switch (index) { 
case 1: 

/* p_selector 
*/ 

p_addr->p_selector->pointer = (Octet *)malloc 
(i*sizeof(Octet) ) ; 

char_to_hex(temp, i, (char *)p_addr->p_selector->pointer, 
& (p_addr->p_selector->length) ) ; 

break; 
case 2: 


.pointer. 


/* s_selector 
*/ 

p_addr->s_selector->pointer = (Octet *)malloc 
(i*sizeof(Octet)); 

char_to_hex(temp, i, (char *)p_addr->s_selector->pointer, 
& (p_addr->s_selector->length) ) ; 

break; 
case 3: 

/* t_selector 
*/ 

p_addr->t_selector->pointer = (Octet *)malloc 
(i*sizeof(Octet)); 

char_to_hex(temp, i, (char *)p_addr->t_selector->pointer, 
& (p_addr->t_selector->length)); 

break; 
default: 

/* nsaps ... could be multiple nsaps. 

* / 

p_addr->nsaps[index - 4].pointer = (Octet *)malloc 
(i*sizeof(Octet)); 

char_to_hex(temp, i, (char *)p_addr->nsaps[index - 


break; 


& (p_addr->nsaps[index - 4],length)); 
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7 * 

** Reset the counters and flags for the next field. 
*/ 

i = 0; 

++j ; 

while (name[j] == '.') { 

/* 

** Move to the next field in the p_addr 
** and the next character in the string. 

*/ 

++index; 

++j; 

} 


else { 

/* 

** Move to the next field in the p_addr and the next 
** character in the string. 

*/ 

++j; 

++index; 


/* 

★ 

~k 

■k k 
■k k 
■k 
~k 
■k 
'k 
~k 
~k 
■k 
•k 

'k ★ 

★ k 
'k ★ 

★ ★ 

★ k 
•k k 
'k k 

★ ★ 

★ k 
'k k 

★ ★ 
★ ★ 
k / 


char_to_hex 

DESCRIPTION: 

Convert a character string of hex characters into a p_addr 
string. 

PARAMETERS 
Inputs: 

ch_string 
ch_length 

Outputs: 

padr_string: P_address byte string 

padr_length: P_address string length 

ALGORITHM: 

Fill the P_address byte string with zeros. 

For each two hex characters in the character string: 

Convert the first character to a 4 bit value. 

Put the value in the 1st 4 bits of the next P_address byte. 
Convert the second character to a 4 bit value. 

Put the value in the last 4 bits of the P_address byte. 

Set the length of the P_address byte string. 


char hex string 
char string length 


378 


Chapter 10 



Example Programs 

Setting Ae_dir_dn and P_address Utility Example 


void 

char_to_hex(ch_string, ch_length, padr_string, padr_length) 
char *ch_string; 

int ch_length; 

char *padr_string; 

Uint32 *padr_length; 

{ 

static char hex[] = "0123456789ABCDEF"; 

int padr_index; 

int ch_index; 

char ch; 

char ^position; 

if (ch_length % 2 != 0) { 

(void)printf("Character string won't fit into P_address field\n"); 
exit(ERROR); 


/* 

** Fill the p_addr byte with zeros. 

*/ 

for (padr_index = 0; padr_index %< (ch_length/2); ++padr_index) 
padr_string[padr_index] = 0x00; 
padr_index = 0; 
ch_index = 0; 

while (ch_index %< ch_length) { 

/* 

** Put the first hex char into first half of byte. 

*/ 

ch = ch_string[ch_index]; 
if (ch == '\0') { 

break; 

} 

position = strchr(hex, ch); 
if (position == NULL) { 

(void)printf("Invalid hex character in P_address\n"); 
exit(ERROR); 

} 

padr_string[padr_index] = (position-hex) %<%< 4; 

++ch_index; 

/* 

** Put the second hex char into second half of byte. 

*/ 

ch = ch_string[ch_index]; 
if (ch == '\0') { 

break; 

} 

position = strchr(hex, ch); 
if (position == NULL) { 

(void)printf("Invalid hex character in P_address\n"); 
exit(ERROR); 

} 

padr_string[padr_index] |= ((position-hex) & OxOF); 
++ch_index; 

++padr_index; 

} 

*padr_length = padr_index; 
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Checking for Errors Example 

This example checks the function return value and the 
result.return_code, result.vendor_code, and diagnostic structures. This 
example also uses printfO statements to print the results. Use this 
routine in conjunction with the first three examples in this chapter: 
Using HLCF Functions Example, Managing FTAM Connections 
Example, and Using LLCS Example. 


#include 

#include 

#include 

/* 

:k k 
:k k 


%</opt/ftam/include/map.h> 
%</opt/ftam/include/mapftam.h> 
%<stdio.h> 


error_handler 


DESCRIPTION: 

This routine is an example of handling failures experienced 
during the FTAM functions. This routine will display the 
error messages. 


** PARAMETERS: 

** INPUT: 

** result : 

** diag : 

k k 
k / 

void 

error_handler(result, diag) 
Api_rc 

struct Ft_diagnostic 


the MAP and HP error information 
the ISO error information 


result; 

*diag; 


Return_code 

Api_rc 

Octet 

Octet 

struct Ft_diagnostic 
/* 

** Initialize 

k / 

return_string = 
vendor_string = 


res; 

outcome; 

*return_string; 
*vendor_string; 
*ft_diag = NULL; 

variables. 

NULL; 

NULL; 
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); 


/* 

** Call ft_gperror to get the printable strings for 
** the return_code and vendor_code. Print the 
** strings returned from ft_gperror. 

*/ 

res = ft_gperror ( & result, & return_string, & vendor_string, & outcome 

if (res == SUCCESS) { 

if (return_string != NULL) { 

(void)printf("FTAM failure: return_code = %s\n", return_string); 
res = ft_fdmemory(return_string, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, ft_diag); 

} 

/* 

** Print the vendor_code if it exists. 

*/ 

if (vendor_string != NULL) { 

(void)printf("FTAM failure: vendor_code = %s\n", vendor_string); 
res = ft_fdmemory(vendor_string, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, ft_diag); 

} 

} 

/* 

** Traverse the diagnostic list and print the further_details strings. 
*/ 

while(diag != NULL) { 

(void)printf("FTAM failure: diagnostic number = %d\n", 
diag->error_id); 

if(diag->further_details != NULL) 

(void)printf("FTAM failure: diagnostic = %s\n", 
diag->further_details); 
diag = diag->next; 

} 

exit(-1); 
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Common Code Example 

This example contains global definitions and common code for the first 
three examples in this chapter: Using HLCF Functions Example, 
Managing FTAM Connections Example, and Using LLCS Functions 
Example. 


/* 
k k 
k k 


ftm_globs.h 


DESCRIPTION: 

This file contains global definitions for the example 
programs illustrating HLCF calls, connection management, 
and LLCS calls. 


k / 

#include 

/* 
k k 


<sys/types.h> 
Constants 


V 


#define 

ERROR 

-1 

#define 

TWO_CONNECTIONS 

2 

#define 

SRC 

0 

#define 

DST 

1 

#define 

SRC_ID 

"src id" 

#define 

SRC_ID_LEN 

6 

#define 

SRC_PW 

"src pw" 

#define 

SRC_PW_LEN 

6 

#define 

SRC_FNAME 

"/tmp/src_fname" 

#define 

DEST_FNAME 

"/tmp/de s t_fname " 

#define 

DEST_ID 

"dest id" 

#define 

DEST_ID_LEN 

7 

#define 

DEST_PW 

"dest pw" 

#define 

DEST_PW_LEN 

7 

#define 

DEL_PW 

"del pw" 

#define 

DEL_PW_LEN 

6 

#define 

CREAT_ID 

"creator" 

#define 

CREAT_PW 

"ere pw" 

#define 

CREAT_PW_LEN 

6 

#define 

LOCAL_INIT 

"/C=us/O=company/OU=division/AP=nodel/ 

AE=ftam_ 

_init" 


#define 

LOCAL_RESP 

"/C=us/O=company/OU=division/AP=nodel/ 

AE=ftam_ 

_resp" 


#define 

REMOTE_RESP 

"/C=us/O=company/OU=division/AP=node2/ 

AE=ftam_ 

_resp" 


#define 

SRC_ACCOUNT 

"account" 

#define 

DEST_ACCOUNT 

"account" 

#define 

STORAGE_ACCOUNT 

"stor_acct" 

#define 

SERVICE_CLASS 

(FT_SC_UNCONSTRAINED | FT_SC_MANAGEMENT 

1 FT_SC_TRANSFER | F T_S C_T RAN S F E R_AND_MG 
1 FT_SC_ACCESS) 

#define 

FUNCTIONAL_UNITS 

(FT_FU_READ | FT_FU_WRITE \ 

1 FT_FU_FILE_ACCESS I FT_FU_LTD_MGMT \ 

1 FT_FU_ENH_MGMT | FT_FU_GROUPING) 


\ 

\ 


382 


Chapter 10 



#define ATTRIBUTE_GROUPS (F T_AG_S TORAGE | FT_AG_SECURITY 

/** Define functions that return values other than integers. 
*/ 

void exit (); 

/* 

** Define the "void" routines in the example routines. 

*/ 


VO 

id 

convert_ddn 

0 ; 

VO 

id 

convert_paddr(); 

VO 

id 

char_to_hex 

0 ; 

VO 

id 

error_handler(); 

VO 

id 

passwords_in(); 

VO 

id 

cat_attribute_in( 

VO 

id 

attribute_i 

n() ; 

VO 

id 

ftam_3(); 


VO 

id 

concur_cntl 

_in () ; 

VO 

id 

fadu_ident_ 

in () ; 

VO 

id 

wait_parm_in(); 

VO 

id 

a e a_p a rm_i n 

0 ; 

VO 

id 

a e d_p a rm_i n 

0 ; 

VO 

id 

c o n_p a rm_i n 

0 ; 

VO 

id 

rre_pa rm_in 

0 ; 

VO 

id 

sel_parm_in 

0 ; 

VO 

id 

des_parm_in 

0 ; 

VO 

id 

ope_parm_in 

0 ; 

VO 

id 

c1o_pa rm_in 

0 ; 

VO 

id 

rat_parm_in 

0 ; 

VO 

id 

cre_pa rm_in 

0 ; 

VO 

id 

b g r_p a rm_i n 

0 ; 

VO 

id 

e g r_p a rm_i n 

0 ; 

VO 

id 

nwc_parm_in 

0 ; 

VO 

id 

r e a_p a rm_i n 

0 ; 

VO 

id 

wri_parm_in 

0 ; 

VO 

id 

s da_p a rm_in 

0 ; 

VO 

id 

rda_pa rm_in 

0 ; 

VO 

id 

e da_p a rm_in 

0 ; 

VO 

id 

e t r_p a rm_i n 

0 ; 

VO 

id 

f c a_p a rm_i n 

0 ; 

VO 

id 

fde_parm_in 

0 ; 

VO 

id 

f c o_pa rm_in 

0 ; 

VO 

id 

exit(); 


si 

ze_ 

_t strlen () ; 


char 

*strchr (); 


VO 

id 

*memcpy(); 



#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
#include "ftm_globs.h" 

#include %<stdio.h> 


Example Programs 

Common Code Example 
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main () 

/* 

** ftm_hlcopy 

k k 


k k 
k k 
k k 
k k 
k k 

* / 

{ 


DESCRIPTION: 

This example program uses high level, context free functions 
synchronously. This program copies a file, changes the 
attributes of the destination file and deletes the source file. 


Ae_label 

Ae_dir_name 

Ft_filename 

Ae_dir_name 

Ft_filename 

Local_event_name 

struct Ft_fcopy_in_dcb 

struct Ft_fcopy_out_dcb 

struct Ft_fcattributes_in_dcb 

struct Ft_fcattributes_out_dcb 

struct Ft_fdelete_in_dcb 

struct Ft_fdelete_out_dcb 

Return_code 

Api_rc 

struct Ft_diagnostic 

(void)printf(”ftm_fcopy: start 
/* 


ae_label; 
source_dirname; 
source_filename; 
destination_dirname; 
destination_filename; 
return_event_name; 

*fco_input_dcb; 

*fco_inout_dcb; 

* fca_input_dcb; 

* fca_inout_dcb; 
*fde_input_dcb; 
*fde_inout_dcb; 
res; 

outcome; 

*diag = NULL; 
ing\n"); 


** Copy the source file to the destination directory. 

k k 


** Get the parameters for ft_fcopy. 

** Call ft_fcopy and verify the outcome. 

k / 

(void)printf("Copying the source file to the destination directory ...\n"); 
fco_parm_in( & source_dirname, & source_filename, 

& destination_dirname, & destination_filename, 

& ae_label, & return_event_name, & fco_input_dcb, 

& fco_inout_dcb ); 

res = ft_fcopy(source_dirname, source_filename, destination_dirname, 
destination_filename, & ae_label, 

return_event_name, fco_input_dcb, & fco_inout_dcb); 
if (res != SUCCESS) 

error_handler(fco_inout_dcb-result, fco_inout_dcb-diagnostic); 

/* 

** Free memory. 

k / 

res = ft_dfdeb((Octet *)fco_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdeb((Octet *)fco_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
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/* 

** Change the attributes of the destination file. 

•k k 


** Get the parameters for ft_fcattributes. 

** Call ft_fcattributes and verify the outcome. 

k / 

(void)printf("Changing attributes of the destination file...\n"); 
fca_parm_in( & destination_dirname, & destination_filename, 

& ae_label, & return_event_name, & fca_input_dcb, 

& fca_inout_dcb ); 

res = ft_fcattributes(destination_dirname, destination_filename, 

& ae_label, return_event_name, fca_input_dcb, 
& fca_inout_dcb) ; 

if (res != SUCCESS) 

error_handler(fca_inout_dcb-result, fca_inout_dcb-diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)fca_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 
res = ft_dfdcb((Octet *)fca_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Delete the source file. 


** Get the parameters for ft_fdelete. 

** Call ft_fdelete and verify the outcome. 

*/ 

(void) printf (''Deleting the source file . . .\n") ; 
fde_parm_in( & source_dirname, & source_filename, 

& ae_label, & return_event_name, & fde_input_dcb, 

& fde_inout_dcb ); 

res = ft_fdelete(source_dirname, source_filename, & ae_label, 

return_event_name, fde_input_dcb, & fde_inout_dcb); 
if (res != SUCCESS) 

error_handler(fde_inout_dcb-result, fde_inout_dcb-diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)fde_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)fde_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(void) printf (''ftm_hlcopy : finished\n") ; 
return(SUCCESS); 
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#include 
tinclude 
#include 
tinclude 
main () 

/* 


%</opt/ftam/include/map.h> 

%</opt/ftam/include/mapftam.h> 
"ftm_globs.h" 

%<stdio.h> 


** ftm_llcopy 

** DESCRIPTION: 

** This example program illustrates how to transfer a file 
** using low level, context sensitive FTAM functions. This 
** program transfers the source file to the destination directory. 


*/ 


Ae_dir_name 
Ae_dir_name 
Ae_label 
Local_event_name 
Connection_id 
Ft_filename 
Ft_filename 
Ft_processing_mode 
Ft_file_actions 
enum Ft_file_status 
enum Ft_access_context 
enum Ft_fadu_operation 
struct Ft_fadu_identity 
struct Ft_contents_type 
Uint16 
Uint16 

struct Ft_data_unit 
struct Ft_aeactivate_in_dcb 
struct Ft_output 
struct Ft_connect_in_dcb 
struct Ft_connect_out_dcb 
struct Ft_relreq_in_dcb 
struct Ft_relreq_out_dcb 
struct Ft_output 
char 

struct Ft_bgroup_out_dcb 
char 

struct Ft_egroup_out_dcb 
struct Ft_select_in_dcb 
struct Ft_select_out_dcb 
struct Ft_create_in_dcb 
struct Ft_create_out_dcb 
struct Ft_rattributes_in_dcb 
struct Ft_rattributes_out_dcb 
struct Ft_open_in_dcb 
struct Ft_open_out_dcb 
char 

struct Ft_read_out_dcb 
char 

struct Ft_write_out_dcb 
struct Ft_rdata_out_dcb 
struct Ft_sdata_out_dcb 
struct Ft_edata_in_dcb 
struct Ft_edata_out_dcb 
char 

struct Ft_etransfer_out_dcb 


my_dirname; 

dirname; 

ae_label; 

return_event_name; 

conn_id[TWO_CONNECTIONS]; 

src_filename; 

dst_filename; 

processing_mode; 

requested_access; 

file_status; 

access_context; 

fadu_operation; 

fadu_identity; 

contents_type; 

threshold; 

des_requested; 

*data_unit; 

*aea_input_dcb; 

*aea_inout_dcb; 

* con_input_dcb; 
*con_inout_dcb; 
*rre_input_dcb; 
*rre_inout_dcb; 
*aed_inout_dcb; 
*bgr_input_dcb; 
*bgr_inout_dcb; 
*egr_input_dcb; 
*egr_inout_dcb; 
*sel_input_dcb; 
*sel_inout_dcb; 
*cre_input_dcb; 
*cre_inout_dcb; 

* rat_input_dcb; 

* rat_inout_dcb; 
*ope_input_dcb; 
*ope_inout_dcb; 
*rea_input_dcb; 
*rea_inout_dcb; 

*wri_input_dcb; 
*wri_inout_dcb; 
*rda_inout_dcb; 
*sda_inout_dcb; 

* e da_input_dcb; 
*eda_inout_dcb; 
*etr_input_dcb; 
*etr_inout_dcb; 
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struct 

Ft_nwcleared_out_dcb 

*nwc_inout_dcb; 

char 


*clo_input_dcb; 

struct 

F t_c1o se_out_dcb 

*clo_inout_dcb; 

char 


*des_input_dcb; 

struct 

Ft_deselect_out_dcb 

*des_inout_dcb; 

Em_t 


t ime ; 

Api_rc 


result; 

struct 

Ft_attributes 

attr_src; 

Return, 

_code 

res; 

Api_rc 


outcome; 

int 


i, j, index; 

Bool 


done; 

struct 

Ft_diagnostic 

*diag = NULL; 


(void)printf("ftm_llcopy: starting\n") ; 
/* 


** Activate "ftam_init". 

•k k 


** Get the parameters for ft_aeactivation. 

** Call ft_aeactivation and verify the outcome. 

k / 

(void)printf("Activating ftam_init...\n"); 

aea_parm_in( & my_dirname, & return_event_name, & aea_input_dcb, 

& aea_inout_dcb, & ae_label ); 

res = ft_aeactivation(my_dirname, return_event_name, aea_input_dcb, 

& aea_inout_dcb, & ae_label); 

if (res != SUCCESS) 

error_handler(aea_inout_dcb-result, diag); 

/* 

** Free memory. 

k / 

res = ft_dfdeb((Octet *) aea_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Establish connections between ftam_init and the responder 
** for the source file and between ftam_init and the responder 
** for the destination file. 

k k 


** Get the parameters for ft_connect. 

** Call ft_connect and verify the outcome. 

k / 

(void)printf("Establishing connections for the source"); 

(void)printf(" & destination files...\n"); 

con_source_parm_in( & return_event_name, & dirname, & con_input_dcb, 
& con_inout_dcb, & conn_id[0] ); 
res = ft_connect(ae_label, return_event_name, dirname, 

con_input_dcb, & con_inout_dcb, & conn_id[0]); 
if (res != SUCCESS) 

error_handler(con_inout_dcb-result, 

con_inout_dcb-connect_out_info-diagnostic) ; 
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/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)con_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)con_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

con_parm_in( & return_event_name, & dirname, & con_input_dcb, 

& con_inout_dcb, & conn_id[l] ); 
res = ft_connect(ae_label, return_event_name, dirname, 

con_input_dcb, & con_inout_dcb, & conn_id[l]); 
if (res !- SUCCESS) 

error_handler(con_inout_dcb-result, 

con_inout_dcb-connect_out_info-diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)con_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)con_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Perform a grouped activity on the source file. 

** ft_bgroup 
** ft_select 

** ft_rattributes 

** ft_egroup 

** Get the parameters for ft_bgroup. 

** Call ft_bgroup and verify the outcome. 

*/ 

(void)printf("Selecting and reading attributes of the source file...\n"); 
bgr_parm_in( & threshold, & return_event_name, & bgr_input_dcb, 

& bgr_inout_dcb ); 

res ; ft_bgroup(conn_id[SRC], threshold, return_event_name, 
bgr_input_dcb, & bgr_inout_dcb); 
if (res != SUCCESS) 

error_handler(bgr_inout_dcb-result, diag); 

/* 


** Get the parameters for ft_select. 

** Call ft_select and verify the outcome. 

*/ 

sel_parm_in( & src_filename, & requested_access, 

& return_event_name, & sel_input_dcb, & sel_inout_dcb ); 
res = ft_select(conn_id[SRC], src_filename, requested_access, 

return_event_name, sel_input_dcb, & sel_inout_dcb); 
if (res != SUCCESS) 

error_handler(sel_inout_dcb-result, sel_inout_dcb-diagnostic); 

/* 


** Get the parameters for ft_rattributes. 

** Call ft_rattributes and verify the outcome. 

*/ 

rat_parm_in( & return_event_name, & rat_input_dcb, & rat_inout_dcb ); 
res = ft_rattributes(conn_id[SRC], return_event_name, rat_input_dcb, 

& rat_inout_dcb); 

if (res != SUCCESS) 

error_handler(rat_inout_dcb-result, rat_inout_dcb-diagnostic); 
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/* 

** Get the parameters for ft_egroup. 

** Call ft_egroup and verify the outcome. 

*/ 

egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); 
res = ft_egroup(conn_id[SRC], return_event_name, egr_input_dcb, 

& egr_inout_dcb) ; 
if (res != SUCCESS) 

error_handler(egr_inout_dcb-result, diag); 

/* 

** Wait on the asynchronous events in the group. 

*/ 

for (i = 1; i %<= 3; ++i) { 

wait_parm_in( & time, & result ); 

res = em_wait(time, & return_event_name, & result); 
if (res != SUCCESS) 

error_handler(result, diag); 
switch (return_event_name) { 

case 1: 

if (bgr_inout_dcb-result.return_code != SUCCESS) 
error_handler(bgr_inout_dcb-result, diag); 
break; 
case 2: 

if (sel_inout_dcb-result.return_code != SUCCESS) 
error_handler(sel_inout_dcb-result, 

sel_inout_dcb-diagnostic) ; 

break; 
case 3: 

if (rat_inout_dcb-result.return_code != SUCCESS) 
error_handler(rat_inout_dcb-result, 

rat_inout_dcb-diagnostic); 

break; 
default: 
break; 

} 


/* 

** Save the attributes of the source 
*/ 

attr_src = rat_inout_dcb-attributes; 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)bgr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)sel_input_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)sel_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)egr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 


f ile. 


& outcome) ; 

& outcome); 

& outcome) ; 

& outcome); 
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/* 

** Open the source file. 

-k 


** Get the parameters for ft_open. 

** Call ft_open and verify the outcome. 

*/ 

(void)printf("Opening the source file...\n"); 
ope_parm_in( & processing_mode, & contents_type, 

& return_event_name, & ope_input_dcb, & ope_inout_dcb); 
res = ft_open(conn_id[SRC], processing_mode, contents_type, 

return_event_name, ope_input_dcb, & ope_inout_dcb); 
if (res != SUCCESS) 

error_handler(ope_inout_dcb-result, ope_inout_dcb-diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)ope_input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 
res = ft_dfdcb((Octet *)ope_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Perform a grouped activity on the destination file. 

** ft_bgroup 
** ft_create 

** ft_open 

** ft_egroup 

■k 


** Get the parameters for ft_bgroup. 

** Call ft_bgroup and verify the outcome. 

*/ 

(void)printf("Creating and opening the destination file...\n"); 
bgr_parm_in( & threshold, & return_event_name, & bgr_input_dcb, 

& bgr_inout_dcb ); 

res = ft_bgroup(conn_id[DST], threshold, return_event_name, 
bgr_input_dcb, & bgr_inout_dcb); 
if (res != SUCCESS) 

error_handler(bgr_inout_dcb-result, diag); 

/* 

** Get the parameters for ft_create. 

** Call ft_create and verify the outcome. 

*/ 

cre_parm_in( & dst_filename, & contents_type, 

& requested_access, & file_status, & return_event_name, 
& cre_input_dcb, & cre_inout_dcb ) ; 

/* 

** Set the attributes and contents_type of the destination file 
** to be identical with those of the source file. 

*/ 

cre_input_dcb-attributes = attr_src; 

contents_type = attr_src.values.contents_type; 

res — ft_create(conn_id[DST], dst_filename, contents_type, 

requested_access, file_status, return_event_name, 
cre_input_dcb, & cre_inout_dcb); 
if (res != SUCCESS) 

error_handler(cre_inout_dcb-result, cre_inout_dcb-diagnostic); 
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/* 

** Get the parameters for ft_open. 

** Call ft_open and verify the outcome. 

*/ 

ope_parm_in( & processing_mode, & contents_type, 

& return_event_name, & ope_input_dcb, & ope_inout_dcb ); 
contents_type = attr_src.values.contents_type; 
return_event_name = 3; 

res = ft_open(conn_id[DST] , processing_mode, contents_type, 

return_event_name, ope_input_dcb, & ope_inout_dcb); 
if (res != SUCCESS) 

error_handler(ope_inout_dcb-result, ope_inout_dcb-diagnostic); 

/* 

** Get the parameters for ft_egroup. 

** Call ft_egroup and verify the outcome. 

*/ 

egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); 
res = ft_egroup(conn_id[DST], return_event_name, egr_input_dcb, 

& egr_inout_dcb); 
if (res != SUCCESS) 

error_handler(egr_inout_dcb-result, diag); 

/* 

** Wait on the asynchronous events in the group. 

*/ 

for (i = 1; i %<= 3; ++i) { 

wait_parm_in( & time, & result ); 

res = em_wait(time, & return_event_name, & result); 
if (res != SUCCESS) 

error_handler(result, diag); 
switch (return_event_name) { 
case 1: 

if (bgr_inout_dcb-result.return_code != SUCCESS) 
error_handler(bgr_inout_dcb-result, diag); 
break; 
case 2: 

if (cre_inout_dcb-result.return_code != SUCCESS) 
error_handler(cre_inout_dcb-result, 

cre_inout_dcb-diagnostic); 

break; 
case 3: 

if (ope_inout_dcb-result.return_code != SUCCESS) 
error_handler(ope_inout_dcb-result, 

ope_inout_dcb-diagnostic); 

break; 
default: 
break; 
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/* 

** Free memory. 

*/ 

res = ft_dfdeb((Octet *)rat_input_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 
res = ft_dfdcb((Octet *)rat_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)bgr_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)cre_input_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)cre_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)ope_input_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)ope_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)egr_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Receive data from the source file. 

■k 


outcome); 

outcome) ; 

outcome); 

outcome) ; 

outcome); 

outcome) ; 

outcome); 

outcome) ; 


** Get the parameters for ft_read. 

** Call ft_read and verify the outcome. 

*/ 

(void)printf("Reading data from the source file"); 

(void)printf("and writing data to the destination file...\n"); 
rea_parm_in( & fadu_identity, & access_context, & return_event_name, 
& rea_input_dcb, & rea_inout_dcb ); 
res = ft_read(conn_id[SRC], fadu_identity, access_context, 

return_event_name, rea_input_dcb, & rea_inout_dcb); 
if (res != SUCCESS) 

error_handler(rea_inout_dcb-result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rea_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Write to the destination file. 

★ 

** Get the parameters for ft_write. 

** Call ft_write and verify the outcome. 

*/ 

wri_parm_in( & fadu_identity , & fadu_operation, & return_event_name, 
& wri_input_dcb, & wri_inout_dcb ); 
res = ft_write(conn_id[DST], fadu_identity, fadu_operation, 

return_event_name, wri_input_dcb, & wri_inout_dcb); 
if (res != SUCCESS) 

error_handler(wri_inout_dcb-result, diag); 
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/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)wri_inout_dcb, & 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Replace the contents of destination 
** of source file. 

*/ 

done = FALSE; 
while ( ! done ) { 

/* 

** Read from the source file. 

■k ~k 


outcome); 


file with the 


contents 


** Get the parameters for ft_rdata. 

** Call ft_rdata and verify the outcome. 

*/ 

rda_parm_in(& des_requested, & return_event_name, & rda_inout_dcb); 
res = ft_rdata(conn_id[SRC], des_requested, return_event_name, 

& rda_inout_dcb); 
if (res != SUCCESS) 

error_handler(rda_inout_dcb-result, 

rda_inout_dcb-diagnostic) ; 

/* 

** If a cancel indication returned, stop 
** transferring data. 

*/ 

data_unit = rda_inout_dcb-data_unit; 

for (index = 1; index %< rda_inout_dcb-des_received; index++) 
data_unit = data_unit-next; 
if (data_unit-structure_id == FT_CANCEL_IND) { 
rda_inout_dcb -data_unit = NULL; 
done = TRUE; 


/* 

** If only a data end indication was returned, 

** stop transfering data. 

*/ 

if (rda_inout_dcb-des_received == 1 & & 

rda_inout_dcb-data_unit-structure_id == FT_DATA_END_IND) { 
rda_inout_dcb -data_unit = NULL; 
done = TRUE; 


/* 
-k ~k 
•k ~k 
~k 
~k 
■k ~k 

* / 
if 


} 


Move the data_element next pointer to the next to the 

last data_element and check for a data end indication 

on the last data_element. If one exists, set the next pointer 

to NULL so the last data_element is not written 

during the ft_sdata call. 

( ! done ) { 

data_unit = rda_inout_dcb-data_unit; 

for (index = 2; index %< rda_inout_dcb-des_received; index ++) 
data_unit = data_unit-next; 

if (data_unit-next-structure_id == FT_DATA_END_IND) { 
data_unit-next = NULL; 
done = TRUE; 
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/* Send data to the destination file. 

■k 

** Get the parameters for ft_sdata. 

** Call ft_sdata and verify the outcome. 

*/ 

if (rda_inout_dcb -data_unit != NULL) { 

sda_parm_in(& return_event_name, & sda_inout_dcb); 
res = ft_sdata(conn_id[DST], rda_inout_dcb-data_unit, 
return_event_name, & sda_inout_dcb); 
if (res != SUCCESS) { 

/* 

** If a "No connection resources" error was returned, 
** wait until the resources are free. 

*/ 

if (res == FTE008_NO_CON_RESOURCES) { 

/* 

** Get the parameters for ft_nwcleared. 

** Call ft_nwcleared and verify the outcome. 

*/ 

nwc_parm_in( & return_event_name, & nwc_inout_dcb ); 
res = ft_nwcleared(conn_id[DST], return_event_name, 

& nwc_inout_dcb); 

if (res != SUCCESS) 

error_handler(nwc_inout_dcb-result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)nwc_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

} 

else { 

error_handler(sda_inout_dcb-result, 

sda_inout_dcb-diagnostic) ; 

} 

} 

/* Free memory. 

*/ 

res = ft_dfdcb((Octet *)sda_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

} 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rda_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 


/* 

** Send a data end to the destination file. 


** Get the parameters for ft_edata. 

** Call ft_edata and verify the outcome. 

*/ 

eda_parm_in(& return_event_name, & eda_input_dcb, & eda_inout_dcb); 
res = ft_edata(conn_id[DST ], return_event_name, eda_input_dcb, 

& eda_inout_dcb); 
if (res != SUCCESS) 

error_handler(eda_inout_dcb-result, eda_inout_dcb-diagnostic); 
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/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)eda_input_dcb, & outcome]; 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)eda_inout_dcb, & outcome]; 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** End the transfer of data to the source and destination files. 

★ 

** Get the parameters for ft_etransfer. 

** Call ft_etransfer and verify the outcome. 

*/ 

(void)printf("Ending data transfer for the source file"); 

(void)printf(" & the destination file...\n"); 
for (i = 0; i %< TWO_CONNECTIONS; ++i) { 

etr_parm_in( & return_event_name, & etr_input_dcb, & etr_inout_dcb ); 
res = ft_etransfer(conn_id[i], return_event_name, etr_input_dcb, 

& etr_inout_dcb); 

if (res != SUCCESS) 

error_handler(etr_inout_dcb-result, etr_inout_dcb-diagnostic); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *) etr_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 


Perform a grouped activity on the source and destination files. 
ft_bgroup 
ft_close 
ft_deselect 
ft_egroup 


** Get the parameters for ft_bgroup. 

** Call ft_bgroup and verify the outcome. 

*/ 

(void)printf("Closing and deselecting the source file"); 

(void)printf(" & the destination file...\n"); 
for (i = 0; i %< TWO_CONNECTIONS; ++i) { 

bgr_parm_in( & threshold, & return_event_name, & bgr_input_dcb, 

& bgr_inout_dcb ) ; 

res = ft_bgroup(conn_id[i], threshold, return_event_name, 
bgr_input_dcb, & bgr_inout_dcb); 
if (res != SUCCESS) 

error_handler(bgr_inout_dcb-result, diag); 

/* 

** Get the parameters for ft_close. 

** Call ft_close and verify the outcome. 

*/ 

clo_parm_in( & return_event_name, & clo_input_dcb, & clo_inout_dcb ); 
res = ft_close(conn_id[i], return_event_name, clo_input_dcb, 

& clo_inout_dcb); 
if (res != SUCCESS) 

error_handler(clo_inout_dcb-result, clo_inout_dcb-diagnostic); 
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/* Get the parameters for ft_deselect. 

** Call ft_deselect and verify the outcome. 

*/ 

des_parm_in( & return_event_name, & des_input_dcb, & des_inout_dcb ); 
res = ft_deselect(conn_id[i], return_event_name, des_input_dcb, 

& des_inout_dcb); 

if (res != SUCCESS) 

error_handler(des_inout_dcb-result, des_inout_dcb-diagnostic); 

/* 

** Get the parameters for ft_egroup. 

** Call ft_egroup and verify the outcome. 

*/ 

egr_parm_in( & return_event_name, & egr_input_dcb, & egr_inout_dcb ); 
res = ft_egroup(conn_id[i], return_event_name, egr_input_dcb, 

& egr_inout_dcb); 
if (res != SUCCESS) 

error_handler(egr_inout_dcb-result, diag); 

/* 

** Wait on the asynchronous events in the group. 

*/ 

for (j = 1; j %<= 3; ++j) { 

wait_parm_in( & time, & result ); 

res = em_wait(time, & return_event_name, & result); 
if (res != SUCCESS) 

error_handler(result, diag); 
switch (return_event_name) { 

case 1: 

if (bgr_inout_dcb-result.return_code != SUCCESS) 
error_handler(bgr_inout_dcb-result, diag); 
break; 
case 2: 

if (clo_inout_dcb-result.return_code != SUCCESS) 
error_handler(clo_inout_dcb-result, 

clo_inout_dcb-diagnostic) ; 

break; 
case 3: 

if (des_inout_dcb-result.return_code != SUCCESS) 
error_handler(des_inout_dcb-result, 

des_inout_dcb-diagnostic) ; 

break; 
default: 
break; 

} 


/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)bgr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)clo_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)des_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 
res = ft_dfdcb((Octet *)egr_inout_dcb, 
if (res != SUCCESS) 

error_handler(outcome, diag); 


& outcome); 

& outcome) ; 

& outcome) ; 

& outcome); 
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/* 

** Release the connections between ftam_init and the 
** responders for the source file and the destination file. 

★ ~k 

** Get the parameters for ft_rrequest. 

** Call ft_rrequest and verify the outcome. 

*/ 

(void)printf("Releasing connections...\n"); 
for (i = 0; i %< TWO_CONNECTIONS; ++i) { 

rre_parm_in( & return_event_name, & rre_input_dcb, & rre_inout_dcb ); 
res = ft_rrequest(conn_id[i], return_event_name, rre_input_dcb, 

& rre_inout_dcb) ; 

if (res != SUCCESS) 

error_handler(rre_inout_dcb-result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdcb((Octet *)rre_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 


/* 

** Deactivate ftam_init 

:k 

** Get the parameters for ft_aedeactivation. 

** Call ft_aedeactivation and verify the outcome. 

*/ 

(void)printf("Deactivating ftam_init...\n"); 
aed_parm_in( & return_event_name, & aed_inout_dcb ); 

res = ft_aedeactivation(ae_label, return_event_name, & aed_inout_dcb); 
if (res != SUCCESS) 

error_handler(aed_inout_dcb-result, diag); 

/* 

** Free memory. 

*/ 

res = ft_dfdeb((Octet *)aed_inout_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(void)printf("ftm_llcopy: finished\n"); 
return(SUCCESS); 
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#include 

tinclude 

#include 

#include 

tinclude 

/* 
k k 


%</opt/ftam/include/map.h> 

%</opt/ftam/include/mapftam.h> 
"ftm_globs.h" 

%<stdio.h> 

%<malloc.h> 


k k 


k k 


aea_parm_in 


k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 


DESCRIPTION: 

This routine assigns valid values to the ft_aeactivation 
program. 


PARAMETERS: 

OUTPUT: 

my_ae_name : 
return_event_name 

input_dcb : 
inout_dcb : 
ae_label : 


the ftam_init name of the user 
gets signalled when the event completes 
default: SYNCHRONOUS 

contains authentication field 
contains return_code field 
AE invocation identifier 


k k 


*/ 


void 

aea_parm_in(my_ae_name, return_event_name, 
ae_label) 


Ae_dir_name 

Local_event_name 

struct Ft_aeactivate_in_dcb 

struct Ft_output 

Ae_label 


*my_ae_name; 

*return_event. 

**input_dcb; 

**inout_dcb; 

*ae_label; 


input_dcb. 


name; 


inout_dcb. 


/* 

** Initialize my_ae_name identifying the local ftam_init. 
*/ 

convert_ddn(my_ae_name, LOCAL_INIT); 

*return_event_name = SYNCHRONOUS; 

/* 

** Initialize input_dcb. 

*/ 

*input_dcb = (struct Ft_aeactivate_in_dcb *)malloc 
(sizeof(struct Ft_aeactivate_in_dcb)) ; 

(*input_dcb)-authentication.pointer = (Octet *)NULL; 
(*input_dcb)-authentication.length = 0; 

(*input_dcb)-my_ae_title_option = No_value_option; 

(*input_dcb)-my_ae_title = NULL; 
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/* 

This is an example for setting the ae_title 

*/ 

/* 

(*input_dcb)-my_ae_title_option = User_object_id_option; 
(*input_dcb)-my_ae_title = (struct Ae_title *)malloc 
(sizeof(struct Object_id)); 

(*input_dcb)-my_ae_title-ae_object_id.length = 6; 

(*input_dcb)-my_ae_title-ae_object_id.element = (Sint32 *)malloc 
(6*sizeof(Sint32) ) ; 

(*input_dcb)-my_ae_title-ae_object_id.element[0] = 1; 

(*input_dcb)-my_ae_title-ae_object_id.element[1] = 3; 

(*input_dcb)-my_ae_title-ae_object_id.element[2] = 9999; 
(*input_dcb)-my_ae_title-ae_object_id.element[3] = 1; 

(*input_dcb)-my_ae_title-ae_object_id.element[4] = 7; 

(*input_dcb)-my_ae_title-ae_object_id.element[5] = 7; 

*/ 

*inout_dcb = NULL; 

*ae_label = 0; 


/* 
■k k 
:k k 
:k k 
•k ~k 
k k 
k k 
k k 


con_parm_in 


DESCRIPTION: 

This routine assigns valid values to the ft_connect parameters. 


k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 


PARAMETERS: 

OUTPUT: 

return_event_name 


called_ae_name : 
input_dcb : 
inout_dcb : 
connection_id : 


gets signalled when the event completes 

default: SYNCHRONOUS 

the AE name of the responder 

contains ft_connect input information 

contains return_code field 

identifies the connection established 


k k 


k / 

void 


con_source_parm_in(return_e 
connection_id) 
L o c al_event_n ame 
Ae_dir_name 

struct Ft_connect_in_dcb 
struct Ft_connect_out_dcb 
Connection_id 
{ 


nt_name, called_ae_name, 

* return_event_name; 
*called_ae_name; 
**input_dcb; 

**inout_dcb; 

*connection_id; 


input_dcb. 


inout_dcb. 
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Return_code res; 

Api_rc outcome; 

struct Ft_diagnostic *diag = NULL; 

/* 

** Initialize the parameters with valid values. 

*/ 

*return_event_name = SYNCHRONOUS; 

/* 

** Initialize the called_ae_name as the DDN identifying the 
** responder. 

*/ 

convert_ddn(called_ae_name, LOCAL_RESP); 

/* 

** Initialize the input_dcb. 

*/ 

res = ft_didcb(FTiConnect, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

/* 

** Set up the presentation address. 

•k k 


** Note: Only the called_ae_dirname OR the called_presentation_address 
** is needed. Both are set up for example purposes only. 

*/ 

/* convert_paddr( & ((*input_dcb)-called_presentation_address) , 

”0102.0102.0102.490003080009011E20FE00" ); */ 

/* 

** Set up the called_ae_title. 

*/ 

/* 6-5-91 MCK: 

* Changed to supply AP-title. 

*/ 

(*input_dcb)-called_ae_title_option = User_object_id_option; 

(*input_dcb)-called_ae_title = (struct Object_id *)malloc 
(sizeof(struct Object_id)); 

(*input_dcb)-called_ae_title-ae_object_id.length = 5; 

(*input_dcb)-called_ae_title-ae_object_id.element = (Sint32 *)malloc 
(5*sizeof(Sint32)); 

(*input_dcb)-called_ae_title-ae_object_id.element[0] = 1; 

(*input_dcb)-called_ae_title-ae_object_id.element[1] = 3; 

(*input_dcb)-called_ae_title-ae_object_id.element[2] = 9999; 

(*input_dcb)-called_ae_title-ae_object_id.element[3] = 1; 

(*input_dcb)-called_ae_title-ae_object_id.element[4] = 7; 

/* 

** Set up the invoke ids. 

*/ 

(*input_dcb)-called_ae_invoke_id = NO_VALUE; 

(*input_dcb)-called_ap_invoke_id = NO_VALUE; 

/* 


** Set up the retry counters and timer. 

*/ 

(*input_dcb)-number_of_retry = 0; 

(*input_dcb)-delay_between_retry = 0; 
(*input_dcb)-connection_resource_wait_timer = 0; 
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/* 

** Set up the context_name for FTAM. 

*/ 

(*input_dcb)-context_name.element = (Sint32 *)malloc(5*sizeof(Sint32)); 
(*input_dcb)-context_name.length = 5; 

(*input_dcb)-context_name.element[0] = 1; 

(*input_dcb)-context_name.element[1] = 0; 

(*input_dcb)-context_name.element[2] = 8571; 

(*input_dcb)-context_name.element[3] = 1; 

(*input_dcb)-context_name.element[4] = 1; 

/* 

** Set up the service_class, functional_units, and attribute_groups. 
*/ 

(*input_dcb)-connect_in_info.service_class = SERVICE_CLASS; 

(*input_dcb)-connect_in_info.functional_units = FUNCTIONAL_UNITS; 
(*input_dcb)-connect_in_info.attribute_groups = ATTRIBUTE_GROUPS; 

/* 

** Set up the quality of service. 

*/ 

(*input_dcb)-connect_in_info.quality_of_service = FT_NO_RECOVERY; 

/* 

** Set up the contents_type_list for FTAM-3 document type. 

*/ 

(*input_dcb)-connect_in_info.contents_type_list = 

(struct Ft_contents_type_element *)malloc 
(sizeof(struct Ft_contents_type_element)); 

(*input_dcb)-connect_in_info.contents_type_list-next_element = NULL; 
ftam_3( & ((*input_dcb)-connect_in_info. 

contents_type_list-contents_type) ); 

/* 

** Set up the initiator_id, account, and file_store_pw. 

*/ 

(*input_dcb)-connect_in_info.initiator_identity = DEST_ID; 

(*input_dcb)-connect_in_info.file_store_pw.length = DEST_PW_LEN; 

(*input_dcb)-connect_in_info.file_store_pw.pointer = (Octet *)DEST_PW; 

(*input_dcb)-connect_in_info.account = DEST_ACCOUNT; 

/* 

** Initialize "inout_dcb". 

*/ 

*inout_dcb = NULL; 

*connection_id = 0; 
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void 

con_parm_in(return_event_name, 
connection_id) 

Local_event_name * 

Ae_dir_name * 

struct Ft_connect_in_dcb * 

struct Ft_connect_out_dcb * 

Connection_id * 


called_ae_name, input_dcb, 

return_event_name; 
called_ae_name; 

*input_dcb; 

*inout_dcb; 
connection_id; 


inout_dcb. 


Return_code 

Api_rc 

struct Ft_diagnostic 
/* 


-k 

* / 


Initialize 


the 


*return_event_name 

/* 


res; 

outcome; 

*diag = NULL; 

parameters with valid 

= SYNCHRONOUS; 


values. 


** Initialize the called_ae_name as the DON identifying the 
** responder. 

*/ 

convert_ddn(called_ae_name, REMOTE_RESP); 

/* 


■k 

*/ 


Initialize the input_dcb. 


res = ft_didcb(FTiConnect, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 

/* 

** Set up the presentation address. 

■k 


/* 


** Note: Only the called_ae_dirname OR the called_presentation_address 
** is needed. Both are set up for example purposes only. 

*/ 

convert_paddr( & ((*input_dcb)-called_presentation_address), 

"0102.0102.0102.490003080009011E20FE00" ); */ 

/* 


** Set up the called_ae_title. 

*/ 

/* 6-5-91 MCK: 

* Changed to supply AP-title. 

*/ 

(*input_dcb)-called_ae_title_option = User_object_id_option; 
(*input_dcb)-called_ae_title = (struct Object_id *)malloc 
(sizeof(struct Object_id)); 

(*input_dcb)-called_ae_title-ae_object_id.length = 5; 

(*input_dcb)-called_ae_title-ae_object_id.element = (Sint32 *)malloc 
(5*sizeof(Sint32)); 

(*input_dcb)-called_ae_title-ae_object_id.element[0] = 1; 

(*input_dcb)-called_ae_title-ae_object_id.element[1] = 3; 

(*input_dcb)-called_ae_title-ae_object_id.element[2] = 9999; 
(*input_dcb)-called_ae_title-ae_object_id.element[3] = 1; 

(*input_dcb)-called_ae_title-ae_object_id.element[4] = 7; 
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/* 

** Set up the invoke ids. 

*/ 

(*input_dcb)-called_ae_invoke_id = NO_VALUE; 

(*input_dcb)-called_ap_invoke_id = NO_VALUE; 

/* 

** Set up the retry counters and timer. 

*/ 

(*input_dcb)-number_of_retry = 0; 

(*input_dcb)-delay_between_retry = 0; 

(*input_dcb)-connection_resource_wait_timer = 0; 

/* 

** Set up the context_name for FTAM. 

*/ 

(*input_dcb)-context_name.element = (Sint32 *)malloc(5*sizeof(Sint32)); 
(*input_dcb)-context_name.length = 5; 

(*input_dcb)-context_name.element[0] = 1; 

(*input_dcb)-context_name.element[1] = 0; 

(*input_dcb)-context_name.element[2] = 8571; 

(*input_dcb)-context_name.element[3] = 1; 

(*input_dcb)-context_name.element[4] = 1; 

/* 

** Set up the service_class, functional_units, and attribute_groups. 

*/ 

(*input_dcb)-connect_in_info.service_class = FT_SC_UNCONSTRAINED 

FT_SC_MANAGEMENT | FT_SC_TRANSFER 
F T_S C_T RAN S F E R_AND_MGMT | FT_SC_ACCESS; 
(*input_dcb)-connect_in_info.functional_units = FT_FU_READ | FT_FU_WRITE 
FT_FU_FILE_ACCESS I FT_FU_LTD_MGMT 
FT_FU_ENH_MGMT | FT_FU_GROUPING; 

/* (*input_dcb)-connect_in_info.attribute_groups = FT_AG_STORAGE 

I FT_AG_SECURITY | FT_AG_PRIVATE; */ 

(*input_dcb)-connect_in_info.attribute_groups = FT_AG_STORAGE 

FT_AG_PRIVATE; 

/* 

** Set up the quality of service. 

*/ 

(*input_dcb)-connect_in_info.quality_of_service = FT_NO_RECOVERY; 

/* 

** Set up the contents_type_list for FTAM-3 document type. 

*/ 

(*input_dcb)-connect_in_info.contents_type_list = 

(struct Ft_contents_type_element *)malloc 
(sizeof(struct Ft_contents_type_element)) ; 

(*input_dcb)-connect_in_info.contents_type_list-next_element = NULL; 
ftam_3( & ((*input_dcb)-connect_in_info. 

contents_type_list-contents_type) ); 

/* 

** Set up the initiator_id, account, and file_store_pw. 

*/ 

(*input_dcb)-connect_in_info.initiator_identity = DEST_ID; 

(*input_dcb)-connect_in_info.file_store_pw.length = DEST_PW_LEN; 

(*input_dcb)-connect_in_info.file_store_pw.pointer = (Octet *)DEST_PW; 
(*input_dcb)-connect_in_info.account = DEST_ACCOUNT; 
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/* 

** Initialize "inout_dcb". 
*/ 

*inout_dcb = NULL; 
*connection_id = 0; 


/* 

■k k 

** rre_parm_in 

k k 

** DESCRIPTION: 

** This routine assigns valid values to the ft_rrequest parameters. 

k k 
k k 

** PARAMETERS: 

** OUTPUT: 

** return_event_name : gets signalled when the event completes 

** default: SYNCHRONOUS 

** input_dcb : input_dcb is NULL 

** inout_dcb : contains return_code field 

k k 
k k 
k / 

void 

rre_parm_in (return_event_name, input_dcb, inout_dcb) 

Local_event_name *return_event_name; 

struct Ft_relreq_in_dcb **input_dcb; 

struct Ft_relreq_out_dcb **inout_dcb; 


/* 

** Initialize the parameters with valid values. 

k / 

*return_event_name = SYNCHRONOUS; 

*input_dcb = NULL; 

*inout_dcb = NULL; 


/* 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k / 


a e d_p a rm_in 


DESCRIPTION: 

This routine assigns valid values to the ft_aedeactivation parameters. 


PARAMETERS: 

OUTPUT: 

return_event_name : gets signalled when the event completes 

default: SYNCHRONOUS 

inout_dcb : contains return_code field 
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void 

aed_parm_in (return_event_name, inout_dcb) 

L o c al_event_n ame *return_event_name; 

struct Ft_output **inout_dcb; 


/* 

** Initialize the parameters with valid values. 
*/ 

*return_event_name = SYNCHRONOUS; 

*inout_dcb = NULL; 


/* 
■k k 

:k k 
:k k 
:k k 
:k k 
:k k 


fco_parm_in 


DESCRIPTION: 

This routine assigns valid values to the ft_fcopy parameters. 


•k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 


PARAMETERS: 

Outputs: 

source_dirname : 
source_filename : 
destination_dirname : 
destination_filename : 
ae_label : 
return_event_name : 

input_dcb : 
inout_dcb : 


name of the source AE directory 

name of the source file 

name of the destination AE directory 

name of the destination file 

label of AE invocation 

gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_fcopy input information 
contains return_code field 


*/ 

void 

fco_parm_in(source_dirname, source_filename, destination_dirname, 

destination_filename, ae_label, return_event_name, input_dcb, 
inout_dcb) 


Ae_dir_name 
Ft_filename 
Ae_dir_name 
Ft_filename 
Ae_label 

Local_event_name 
struct Ft_fcopy_in_dcb 
struct Ft_fcopy_out_dcb 


*source_dirname; 

*source_filename; 
*destination_dirname; 
*destination_filename; 
*ae_label; 

* return_event_name; 

**input_dcb; 

**inout_dcb; 


Return_code 

Api_rc 

struct Ft_diagnostic 


res; 

outcome; 

*diag = NULL; 
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/* 

** Set the directory distinguished names to identify the 
** responders on the source and destination nodes. 

*/ 

convert_ddn(source_dirname, LOCAL_RESP); 
convert_ddn(destination_dirname, REMOTE_RESP); 

/* 

** Initialize the filenames. 

*/ 

*source_filename = SRC_FNAME; 

*destination_filename = DEST_FNAME; 

*ae_label = NULL; 

*return_event_name = SYNCHRONOUS; 

/* 

** Initialize the input_dcb. 

*/ 

res = ft_didcb(FTiFCopy, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(*input_dcb)-source_init_id = SRC_ID; 

(*input_dcb)-source_filestore_pw.pointer = (Octet *)SRC_PW; 

(*input_dcb)-source_filestore_pw.length = SRC_PW_LEN; 
(*input_dcb)-source_account = SRC_ACCOUNT; 
passwords_in( & ((*input_dcb)-source_file_passwords) ); 
(*input_dcb)-dest_init_id = DEST_ID; 

(*input_dcb)-dest_filestore_pw.pointer = (Octet *)DEST_PW; 
(*input_dcb)-dest_filestore_pw.length = DEST_PW_LEN; 
(*input_dcb)-dest_account = DEST_ACCOUNT; 
passwords_in( & ((*input_dcb)-dest_file_passwords) ); 

(*input_dcb)-create_file_pw.pointer = (Octet *)CREAT_PW; 

(*input_dcb)-create_file_pw.length = CREAT_PW_LEN; 
(*input_dcb)-overwrite = FT_RECREATE_FILE; 

/* 

** Initialize the inout_dcb. 

*/ 

*inout_dcb = NULL; 


406 


Chapter 10 



Example Programs 

Common Code Example 


/* 
■k k 


** fca_parm_in 

■k k 


k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 
k k 


DESCRIPTION: 

This routine assigns valid values to the ft_fcattributes parameters. 


PARAMETERS: 

Outputs: 
dirname : 
filename : 
ae_label : 
return_event_name 

input_dcb : 
inout_dcb : 


name of the AE directory 
name of the file 
label of AE invocation 

gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_fcattributes input information 
contains return_code field 


k / 

void 

fca_parm_in(dirname, filename, 
inout_dcb) 

Ae_dir_name 
Ft_filename 
Uint32 

Local_event_name 

struct Ft_fcattributes_in_dcb 

struct Ft_fcattributes_out_dcb 


ae_label, return_event_name 

*dirname; 

*filename; 

*ae_label; 

* return_event_name; 

* *input_dcb; 

**inout_dcb; 


input_dcb. 


Return_code res; 

Api_rc outcome; 

struct Ft_diagnostic *diag = NULL; 

/* 

** Set the directory distinguished name to identify the responder 
** on the desired node. 

k / 

convert_ddn (dirname, REMOTE_RESP) ; 

*filename = DE S T_FNAME; 

*ae_label = 0; 

*return_event_name = SYNCHRONOUS; 

/* 

** Initialize the input_dcb. 

k / 

res = ft_didcb(FTiFCattributes, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(*input_dcb)-init_id = DEST_ID; 

(*input_dcb)-filestore_pw.pointer = (Octet *)DEST_PW; 

(*input_dcb)-filestore_pw.length = DEST_PW_LEN; 
passwords_in( & ((*input_dcb)-file_passwords) ); 
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/* 

** Set up the changed attributes. 

*/ 

(*input_dcb)-attribute_names |= FT_AN_STORAGE_ACCT 

FT_AN_FILE_A VAIL ABILITY | FT_AN_FUTURE_FILESIZE 
F T_AN_LE GAL_QUAL 
F T_AN_P RI VAT E_U S E ; 

cat_attribute_in( & ((*input_dcb)-attributes) ); 

(*input_dcb)-account = DEST_ACCOUNT; 

/* 

** Initialize the inout_dcb. 

*/ 

*inout_dcb = NULL; 


/* 
k k 

** fde_parm_in 

k k 

** DESCRIPTION: 

** This routine assigns valid values to the ft_fdelete parameters. 

k k 


k k 

** PARAMETERS: 

** Outputs: 

** dirname : 

** filename : 

** ae_label : 

** return_event_name : 

k k 

** input_dcb : 

** inout_dcb : 

k k 
k / 

void 

fde_parm_in(dirname, filename, 
inout_dcb) 

Ae_dir_name 
Ft_filename 
Uint32 

Local_event_name 

struct Ft_fdelete_in_dcb 

struct Ft_fdelete_out_dcb 


name of the AE directory 
name of the file 
label of AE invocation 

gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_fdelete input information 
contains return_code field 


ae_label, return_event_name, input_dcb, 

*dirname; 

*filename; 

*ae_label; 

*return_event_name; 

**input_dcb; 

**inout_dcb; 


Return_code 

Api_rc 

struct Ft_diagnostic 
/* 


res; 

outcome; 

*diag = NULL; 


** Set the directory distinguished name 
** responder. 

k / 

convert_ddn(dirname, LOCAL_RESP); 

*filename = SRC_FNAME; 

*ae_label = 0; 

*return_event_name = SYNCHRONOUS; 


to 


identify the desired 
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/* 

** Initialize the input_dcb. 

*/ 

res = ft_didcb(FTiFDelete, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(*input_dcb)-init_id = SRC_ID; 

(*input_dcb)-filestore_pw.pointer = (Octet *)SRC_PW; 

(*input_dcb)-filestore_pw.length = SRC_PW_LEN; 

(*input_dcb)-delete_file_pw.pointer = (Octet *)DEL_PW; 

(*input_dcb)-delete_file_pw.length = DEL_PW_LEN; 

(*input_dcb)-account = DEST_ACCOUNT; 

/* 

** Initialize the inout_dcb. 

*/ 

*inout_dcb = NULL; 


/* 
:k k 
:k k 
: k ~k 
:k ~k 
:k ~k 
•k k 
k k 


sel_parm_in 


DESCRIPTION: 

This routine assigns valid values to the ft_select parameters. 


** PARAMETERS: 

** Outputs: 

** filename : 

** requested_access : 

** return_event_name : 

k k 

** input_dcb : 

** inout_dcb : 


name of the file to select 
requested file action 

gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_select input information 
contains return_code field 


k / 

void 

sel_parm_in(filename, reque 
inout_dcb) 

Ft_filename 
Ft_file_actions 
Local_event_name 
struct Ft_select_in_dcb 
struct Ft_select_out_dcb 
{ 


ted_access, return_event_name, 

*filename; 

*requested_access; 
*return_event_name; 
**input_dcb; 

**inout_dcb; 


input_dcb. 
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Api_rc outcome; 

Return_code res; 

struct Ft_diagnostic *diag = NULL; 

/* 

** Initialize the parameters with valid values. 

*/ 

*filename = SRC_FNAME; 

*requested_access = FT_FA_READ | FT_FA_REPLACE 

FT_FA_EXTEND | FT_FA_ERASE | FT_FA_READ_ATTRIBUTE 
FT_FA_CHANGE_ATTRIBUTE | FT_FA_DELETE_FILE; 
*return_event_name = 2; 

/* 

** Initialize the input_dcb. 

*/ 

res = ft_didcb(FTiSelect, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 
attribute_in( & ((*input_dcb)-attributes) ); 
passwords_in( & ((*input_dcb)-file_passwords) ); 

(*input_dcb)-account = DEST_ACCOUNT; 

(*input_dcb)-concurrency_control = (struct Ft_concurrency_control *) 
malloc(sizeof(struct Ft_concurrency_control)); 
concur_cntl_in( & ((*input_dcb)-concurrency_control) ); 

/* 

** Initialize the inout_dcb. 

*/ 

*inout_dcb = NULL; 


/* 

■k ~k 

** des_parm_in 

•k k 


** DESCRIPTION: 

** This routine assigns valid values to the ft_deselect parameters. 

k k 
k k 


** PARAMETERS: 

** Outputs: 

** return_event_name : 

k k 

** input_dcb : 

** inout_dcb : 

k k 
k / 

void 

des_parm_in(return_event_name, 

Local_event_name 

char 

struct Ft_deselect_out_dcb 

{ 


gets signalled when the event completes 
default: SYNCHRONOUS 

input_dcb is NULL 
contains return_code field 


input_dcb, inout_dcb) 

* return_event_name; 

* *input_dcb; 
**inout_dcb; 
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/* 

** Initialize the parameters with valid values. 
*/ 

*return_event_name = 3; 

*input_dcb = NULL; 

*inout_dcb = NULL; 


/* 
k k 

** rat_parm_in 

k k 


** DESCRIPTION: 

** This routine assigns valid values to the ft_rattributes parameters. 

k k 
k k 


** PARAMETERS: 

** Outputs: 

** return_event_name : 

k k 

** input_dcb : 

** inout_dcb : 

k k 
k / 

void 

rat_parm_in(return_event_name, 
Local_event_name 
struct Ft_rattributes_in_dcb 
struct Ft_rattributes_out_dcb 


gets signalled when the event completes 
default: SYNCHRONOUS 

contains Ft_attributes_name field 
contains return_code field 


input_dcb, inout_dcb) 
*return_event_name; 

* *input_dcb; 
**inout_dcb; 


Api_rc outcome; 

Return_code res; 

struct Ft_diagnostic *diag = NULL; 

/* 

** Initialize the parameters with valid values. 

k / 

*return_event_name = 3; 

res = ft_didcb(FTiReadattributes, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(*input_dcb)-attribute_names = FT_AN_PERMITTED_ACTIONS 
| FT_AN_CONTENT_TYPE 
| FT_AN_ID_OF_CREATOR 
| FT_AN_ACCESS_CONTROL; 

*inout_dcb = NULL; 
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/* 

■k k 

** ope_parm_in 

:k k 


** DESCRIPTION: 

** This routine assigns valid values to the ft_open parameters. 

k k 
k k 


** PARAMETERS: 

** Outputs: 

** processing_mode : 

** contents_type : 

** return_event_name 

k k 

** input_dcb : 

** inout_dcb : 

k k 


type of permission 
document type 

gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_open input information 
contains return_code field 


k / 

void 

ope_parm_in(processing_mode, contents_type, 
input_dcb, inout_dcb) 


return_event_name, 


Ft_processing_mode 
struct Ft_contents_type 
Local_event_name 
struct Ft_open_in_dcb 
struct Ft_open_out_dcb 


^processing_mode; 

*contents_type; 
*return_event_name; 
**input_dcb; 
**inout_dcb; 


Api_rc 

Return_code 

struct Ft_diagnostic 


outcome; 

res; 

*diag = NULL; 


/* 

** Initialize the parameters with valid values. 

*/ 

*processing_mode = FT_PM_READ | FT_PM_REPLACE 
| FT_PM_EXTEND | FT_PM_ERASE; 
ftam_3(contents_type); 

*return_event_name = SYNCHRONOUS; 

/* 

** Initialize the input_dcb. 

*/ 

res = ft_didcb(FTiOpen, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag) ; 

(*input_dcb)-concurrency_control = (struct Ft_concurrency_control *) 
malloc(sizeof(struct Ft_concurrency_control)); 
concur_cntl_in( & ((*input_dcb)-concurrency_control) ); 

/* 

** Initialize the inout_dcb. 

*/ 

*inout_dcb = NULL; 
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/* 

■k k 

** clo_parm_in 

:k k 


** DESCRIPTION: 

** This routine assigns valid values to the ft_close parameters. 

k k 

** PARAMETERS: 

** Outputs: 

** return_event_name : gets signalled when the event completes 

** default: SYNCHRONOUS 

** input_dcb : input_dcb is NULL 

** inout_dcb : contains return_code field 

k / 

void 

clo_parm_in(return_event_name, input_dcb, inout_dcb) 

Local_event_name *return_event_name; 

char **input_dcb; 

struct Ft_close_out_dcb **inout_dcb; 


/* 

** Initialize the parameters with all valid values. 

k / 

*return_event_name = 2; 

*input_dcb = NULL; 

*inout_dcb = NULL; 


/* 
k k 

** cre_parm_in 

k k 

** DESCRIPTION: 

** This routine assigns valid values to the ft_create parameters. 

k k 


** PARAMETERS: 


Outputs: 

filename : 
contents_type : 
requested_access : 
file_status : 
return_event_name : 

input_dcb : 
inout_dcb : 


name of file to create 
type of document 
type of file access 
state of the file 

gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_create input information 
contains return_code field 


void 

cre_parm_in(filename, contents_type, requested_access, 
return_event_name, input_dcb, inout_dcb) 


Ft_filename 

struct Ft_contents_type 
Ft_file_actions 
enum Ft_file_status 
Local_event_name 
struct Ft_create_in_dcb 
struct Ft_create_out_dcb 
{ 


*filename; 

*contents_type; 

*requested_access; 

*file_status; 

*return_event_name; 

**input_dcb; 

**inout_dcb; 


file_status. 
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Api_rc outcome; 

Return_code res; 

struct Ft_diagnostic *diag = NULL; 

/* 

** Initialize the parameters with valid values. 

*/ 

*filename = DE S T_FNAME; 
ftam_3(contents_type); 

*requested_access = FT_FA_READ | FT_FA_REPLACE 

I FT_FA_EXTEND | FT_FA_ERASE | FT_FA_READ_ATTRIBUTE 
I FT_FA_CHANGE_ATTRIBUTE | F T_F A_D E L E T E_FILE; 
*file_status = FT_NEW; 

*return_event_name = 2; 

/* 

** Initialize the input_dcb. 

*/ 


} 

/* 
k k 

k k 
k k 
k k 


res = ft_didcb(FTiCreate, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(*input_dcb)-concurrency_control = (struct Ft_concurrency_control 
malloc(sizeof(struct Ft_concurrency_control)) ; 
concur_cntl_in( & ((*input_dcb)-concurrency_control) ); 

(*input_dcb)-create_file_pw.pointer = (Octet *)CREAT_PW; 

(*input_dcb)-create_file_pw.length = CREAT_PW_LEN; 
passwords_in( & ((*input_dcb)-file_passwords) ); 

(*input_dcb)-account = DEST_ACCOUNT; 

/* 

** Initialize the inout_dcb. 

k / 

*inout_dcb = NULL; 


DESCRIPTION: 

This routine assigns 


bgr_parm_in 
valid values to the 


ft_bgroup parameters. 


*) 


** PARAMETERS: 
** Outputs: 

k k 
k k 
k k 
k k 
k k 


threshold : 
return event name 


input_dcb : 
inout_dcb : 

*/ 

void 

bgr_parm_in(threshold, return, 
Uint16 

Local_event_name 

char 

struct Ft_bgroup_out_dcb 


number of calls within the group 

gets signalled when the event completes 

default: SYNCHRONOUS 

contains ft_bgroup input information 

contains return_code field 


event_name, input_dcb, inout_dcb) 
^threshold; 

*return_event_name; 

**input_dcb; 

**inout_dcb; 
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/* 

** Initialize the parameters with all valid values. 
*/ 

*return_event_name = 1; 

*threshold = 2; 

*input_dcb = NULL; 

*inout_dcb = NULL; 


/* 
■k k 
:k k 
:k k 
:k ~k 
: k ~k 
:k 

:k ~k 


egr_parm_in 


DESCRIPTION: 

This routine assigns valid values to the ft_egroup parameters. 


** PARAMETERS: 

** Outputs: 

** return_event_name : 

•k ~k 

** input_dcb : 

** inout_dcb : 

k k 
k / 

void 

egr_parm_in (return_event_name 

Local_event_name 

char 

struct Ft_egroup_out_dcb 


gets signalled when the event 
default: SYNCHRONOUS 

input_dcb is NULL 
contains return_code field 


input_dcb, inout_dcb) 
return_event_name; 
*input_dcb; 
*inout_dcb; 


completes 


/* 

** Initialize the parameters with valid values. 

k / 

*return_event_name = SYNCHRONOUS; 

*input_dcb = NULL; 

*inout_dcb = NULL; 
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/* 

■k k 

** rea_parm_in 

:k k 


** DESCRIPTION: 

** This routine assigns valid values to the ft_read parameters. 

k k 
k k 


** PARAMETERS: 

** Outputs: 

** fadu_identity : 

** access_context : 

** return_event_name 

k k 

** input_dcb : 

** inout_dcb : 

k k 
k / 

void 

rea_parm_in(fadu_identity, 
inout_dcb) 
struct Ft_fadu_identity 
enum Ft_access_context 
Local_event_name 
char 

struct Ft_read_out_dcb 


FADU identifier 
file structure 

gets signalled when the event completes 
default: SYNCHRONOUS 

input_dcb is NULL 
contains return_code field 


access_context, return_event_name, input_dcb, 

*fadu_identity; 

*access_context; 

*return_event_name; 

**input_dcb; 

* *inout_dcb; 


/* 

** Initialize the parameters with valid values. 

k / 

f adu_ident_in (fadu_identity) ; 

*access_context = FT_UNSTRUCTURED_ALL_DATA_UNITS; 
*return_event_name = SYNCHRONOUS; 

*input_dcb = NULL; 

*inout_dcb = NULL; 


/* 
k k 

** wri_parm_in 

k k 


** DESCRIPTION: 

** This routine assigns valid values to the ft_write parameters. 

k k 


** PARAMETERS: 

** Outputs: 

** fadu_identity : 

** fadu_operation : 

** return_event_name 

k k 

** input_dcb : 

** inout_dcb : 


FADU identifier 

type of write to perform 

gets signalled when the event completes 

default: SYNCHRONOUS 

input_dcb is NULL 

contains return_code field 


k / 

void 

wri_parm_in (fadu_identity, fadu_operation, return_event_name, input_dcb, 
inout_dcb) 
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struct Ft_fadu_identity 
enum Ft_fadu_operation 
Local_event_name 
char 

struct Ft_write_out_dcb 


*fadu_identity; 

*fadu_operation; 
*return_event_name; 

* *input_dcb; 

* *inout_dcb; 


/* 

** Initialize the parameters with valid values. 
*/ 

fadu_ident_in(fadu_identity); 

*fadu_operation = FT_REPLACE; 

*return_event_name = SYNCHRONOUS; 

*input_dcb = NULL; 

*inout_dcb = NULL; 


/* 
k k 
k k 
k k 
k k 
k k 
k k 
k k 


sda_parm_in 


DESCRIPTION: 

This routine assigns valid values to the ft_sdata parameters. 


** PARAMETERS: 

** Outputs: 

** return_event_name : gets signalled when the event completes 

** default: SYNCHRONOUS 

** data_unit : Actual data to send 

** inout_dcb : contains return_code field 

k k 
k / 

void 

sda_parm_in(return_event_name, inout_dcb) 

L o c al_event_n ame *return_event_name; 

struct Ft_sdata_out_dcb **inout_dcb; 


/* 

** Initialize the parameters with valid values. 

k / 

*return_event_name = SYNCHRONOUS; 

*inout_dcb = NULL; 
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/* 

■k k 

** rda_parm_in 

:k k 


** DESCRIPTION: 

** This routine assigns valid values to the ft_rdata parameters. 

k k 
k k 


** PARAMETERS: 

** Outputs: 

** des_requested : 

** return_event_name 

k k 

** inout_dcb : 

k k 
k / 

void 

rda_parm_in(des_requested, 

Local_event_name 

Uint16 

struct Ft_rdata_out_dcb 


number of FADUs requested to receive 
gets signalled when the event completes 
default: SYNCHRONOUS 

contains return_code field 


return_event_name, inout_dcb) 
*return_event_name; 
*des_requested; 
**inout_dcb; 


/* 

** Initialize the parameters with valid values. 

k / 

*des_requested = 10; 

*return_event_name = SYNCHRONOUS; 

*inout_dcb = NULL; 


/* 
k k 
k k 
k k 
k k 
k k 
k k 
k k 


eda_parm_in 


DESCRIPTION: 

This routine assigns valid values to the ft_edata parameters. 


** PARAMETERS: 

** Outputs: 

** return_event_name : 

k k 

** input_dcb : 

** inout_dcb : 

k k 
k / 

void 

eda_parm_in(return_event_name, 
Local_event_name 
struct Ft_edata_in_dcb 
struct Ft_edata_out_dcb 


gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_edata input information 
contains return_code field 


input_dcb, inout_dcb) 
*return_event_name; 
**input_dcb; 
**inout_dcb; 


Api_rc 

Return_code 

struct Ft_diagnostic 


outcome; 

res; 

*diag = NULL; 
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/* 

** Initialize the parameters with all valid values. 

*/ 

*return_event_name = SYNCHRONOUS; 

res = ft_didcb(FTiDataEnd, 0, (Octet **)input_dcb, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, diag); 

(*input_dcb)-action_result = FT_AR_SUCCESS; 

(*input_dcb)-diagnostic = NULL; 

*inout_dcb = NULL; 


/* 
■k ~k 

:k ~k 
:k 

:k ~k 
:k ~k 


etr_parm_in 

DESCRIPTION: 

This routine assigns valid values to the ft_etransfer parameters. 


:k ~k 
:k 

:k ~k 
:k ~k 
:k ~k 
:k ~k 


PARAMETERS: 

Outputs: 

return_event_name 

input_dcb : 
inout_dcb : 


gets signalled when the event completes 
default: SYNCHRONOUS 

contains ft_etransfer input information 
contains return_code field 


*/ 

void 

etr_parm_in(return_event_name, input_dcb, inout_dcb) 
Local_event_name *return_event_name; 

char **input_dcb; 

struct Ft_etransfer_out_dcb **inout_dcb; 


/* 

** Initialize the parameters with all valid values. 
*/ 

*return_event_name = SYNCHRONOUS; 

*input_dcb = NULL; 

*inout_dcb = NULL; 
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/* 

■k k 

** wait_parm_in 

:k k 

** DESCRIPTION: 

** This routine sets up the parameter values and the expected 
** outcome values for em_wait calls. This routine allows 
** the test programs to specify which set of parameter values 
** you want to set. 

■k k 
:k k 


** PARAMETERS: 

** OUTPUT: 

** time : 

** result : 

•k ~k 
*/ 

void 

wait_parm_in(time, result) 

Em_t 

Api_rc 


timeout value 

contains return_code field for em_wait 


*time; 
*result; 


/* 

** Initialize "time" to infinite. 
*/ 

*time = -1; 

/* 

** Initialize "result". 

*/ 

result-return_code = 9999; 
result-vendor_code = 9999; 


/* 
k k 

** passwords_in 

k k 

** DESCRIPTION: 

** This routine assigns valid values to the file_passwords structure. 

k k 
k k 

** PARAMETERS: 

** Outputs: 

** file_passwords : pointer to the Ft_file_passwords structure 

k k 
k / 

void 

passwords_in(file_passwords) 

struct Ft_file_passwords *file_passwords; 

{ 
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/* 

** Initialize all fields of the Ft_file_passwords structure. 
*/ 

file_passwords-read.length = 4; 
file_passwords-read.pointer = (Octet *)"read"; 
file_passwords-insert.length = 6; 

file_passwords-insert.pointer = (Octet *)"insert"; 
file_passwords-replace.length = 7; 

file_passwords-replace.pointer = (Octet *)"replace"; 
file_passwords-extend.length = 6; 

file_passwords-extend.pointer = (Octet *)"extend"; 
file_passwords-erase.length = 5; 

file_passwords-erase.pointer = (Octet *)"erase"; 
file_passwords-read_attribute.length = 8; 

file_passwords-read_attribute.pointer = (Octet *)"readattr"; 
file_passwords-change_attribute.length = 8; 

file_passwords-change_attribute.pointer = (Octet *)"chngattr"; 
file_passwords-delete_file.length = 8; 

file_passwords-delete_file.pointer = (Octet *)"delefile"; 


/* 

■k k 

** cat_attribute_in 

k k 

** DESCRIPTION: 

** This routine assigns valid values to the Ft_attributes structure 
** for the ft_cattributes and ft_fcattributes calls. 

k k 
k k 

** PARAMETERS: 

** Outputs: 

** attributes : pointer to the Ft_attributes structure 

k k 
* / 

void 

cat_attribute_in(attributes) 

struct Ft_attributes *attributes; 

{ 

/* 

** Initialize all fields in Ft_attributes structure. 

*/ 

attributes-mask = 0; 

/* 

** Change the storage_account. 

*/ 

attributes-values.storage_account = STORAGE_ACCOUNT; 

/* 

** Change the file_availability. 

*/ 

attributes-values.file_availability = FT_IMMEDIATE_AVAIL; 

/* 

** Change the future_filesize. 

*/ 

attributes-values.future_filesize = 1000000; 


Chapter 10 


421 



Example Programs 

Common Code Example 


/* 

** Change the legal_qualification. 

*/ 

attributes-values.legal_qualification = "I'm_bad"; 

/* 

** Change the private_use. 

*/ 

attributes-values.private_use.pointer = (Octet *)"private"; 
attributes-values.private_use.length = 7; 


/* 

★ ★ 

** ftam_3 

★ ★ 


** DESCRIPTION: 

** This routine assigns a ftam_3 document type to the Ft_contents_type 
** structure. 


** PARAMETERS: 

** Outputs: 

** cont_type : pointer to the Ft_contents_type structure 

k k 
k / 

void 

ftam_3(cont_type) 

struct Ft_contents_type *cont_type; 

{ 

struct Ft_dt_ftam_3 *ftm_3; 

/* 

** Initialize all fields of the Ft_contents_type structure. 

k / 

cont_type-contents_form = FT_DOCUMENT_TYPE; 

ftm_3 = (struct Ft_dt_ftam_3 *)malloc(sizeof(struct Ft_dt_ftam_3)); 
cont_type-contents_info.document.name.element = 

(Sint32 *)malloc(5*sizeof(Sint32)); 
ftm_3-string_length = 512; 

ftm_3-significance = FT_SS_NO_SIGNIFICANCE; 

cont_type-contents_info.document.parameters = (char *)ftm_3; 
cont_type-contents_info.document.name.length = 5; 
cont_type-contents_info.document.name.element[0]=1; 
cont_type-contents_info.document.name.element[1]=0; 
cont_type-contents_info.document.name.element[2]=8571; 
cont_type-contents_info.document.name.element[3]=5; 
cont_type-contents_info.document.name.element[4]=3; 
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/* 

■k k 

** attribute_in 

:k k 

** DESCRIPTION: 

** This routine assigns valid values to the Ft_attribute structure. 


** PARAMETERS: 

** Outputs: 

** attributes : pointer to the attributes structure 

k k 
*/ 

void 

attribute_in(attributes) 

struct Ft_attributes *attributes; 


{ 

/* 

** Initialize all fields of Ft_attributes structure. 

*/ 

attributes-mask = FT_AN_FILENAME | FT_AN_PERMITTED_ACTIONS 
FT_AN_CONTENT_TYPE | FT_AN_STORAGE_ACCT 
FT_AN_ID_OF_CREATOR I FT_AN_ID_OF_MODIFIER 
FT_AN_ID_OF_READER | FT_AN_ID_OF_ATT_MOD 
FT_AN_FILE_AVAILABILITY | FT_AN_FUTURE_FILESIZE 
FT_AN_LEGAL_QUAL | FT_AN_PRIVATE_USE; 
attributes-values.filename = SRC_FNAME; 

attributes-values.permitted_actions = FT_PA_READ | FT_PA_REPLACE 
FT_PA_EXTEND | FT_PA_ERASE | FT_PA_READ_ATTRIBUTE 
FT_PA_CHANGE_ATTRIBUTE | FT_PA_DELETE_FILE; 
ftam_3( & (attributes-values.contents_type) ); 
attributes-values.storage_account = STORAGE_ACCOUNT; 
attributes-values.identity_of_creator = CREAT_ID; 
attributes-values.access_control.delete_ace = NULL; 
attributes-values.access_control.insert_ace = NULL; 
attributes-values.file_availability = FT_DEFERRED_AVAIL; 
attributes-values.future_filesize = 1000; 
attributes-values.legal_qualification = "legal_qual"; 
attributes-values.private_use.pointer = (Octet *)"private"; 
attributes-values.private_use.length = 7; 
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/* 

■k k 

** concur_cntl_in 

:k k 

** DESCRIPTION: 

** This routine assigns valid values to the Ft_concurrency_control 
** structure. 

k k 
k k 

** PARAMETERS: 

** Outputs: 

** concurrency_control : pointer to the Ft_concurrency_control 

** structure 

k k 
k / 

void 

concur_cntl_in(concurrency_control) 

struct Ft_concurrency_control **concurrency_control; 

{ 

/* 

** Initialize the Ft_concurrency_control structure. 

k / 

*concurrency_control = NULL; 


/* 
k k 

** fadu_ident_in 

k k 

** DESCRIPTION: 

** This routine assigns valid values to the Ft_fadu_identity structure. 

k k 
k k 

** PARAMETERS: 

** Outputs: 

** fadu_identity : pointer to the Ft_fadu_identity structure 

k k 
*/ 

void 

fadu_ident_in(fadu_identity) 

struct Ft_fadu_identity *fadu_identity; 


/* 

** Initialize all fields of Ft_fadu_identity structure. 
*/ 

fadu_identity-fadu_form = FT_FADU_LOCATION; 
fadu_identity-fadu_info.fadu_location = FT_FIRST; 
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/* 

■k k 

** nwc_parm_in 

:k k 


** DESCRIPTION: 

** This routine assigns values to the ft_nwcleared parameters. 

k k 
k k 


** PARAMETERS: 

** OUTPUT: 

** return_event_name : 

k k 

** inout_dcb : 

k k 
k k 
k / 

void 

nwc_parm_in(return_event_name, 

Local_event_name 

struct Ft_nwcleared_out_dcb 


gets signalled when the event completes 
default: SYNCHRONOUS 

contains return_code field 


inout_dcb) 

*return_event_name; 
**inout_dcb; 


/* 

** Initialize the parameters with valid values. 

k / 

*return_event_name = SYNCHRONOUS; 

*inout_dcb = NULL; 
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#include %</opt/ftam/include/map.h> 
#include %</opt/ftam/include/mapftam.h> 
#include %<stdio.h> 
void exit(); 

/* 

** error_handler 

k k 


DESCRIPTION: 

This routine is an example of handling failures experienced 
during the FTAM functions. This routine will display the 
error messages. 


** PARAMETERS: 

** INPUT: 

** result : 

** diag : 

k k 
k / 

void 

error_handler(result, diag) 
Api_rc 

struct Ft_diagnostic 
{ 


the MAP and HP error information 
the ISO error information 


result; 

*diag; 


Return 

Api_rc 

Octet 

Octet 

struct 


) ; 


.code res; 

outcome; 

*return_string; 

*vendor_string; 

Ft_diagnostic *ft_diag = NULL; 

/* 

** Initialize variables. 

*/ 

return_string = NULL; 
vendor_string = NULL; 

/* 

** Call ft_gperror to get the printable strings for 
** the return_code and vendor_code. Print the 
** strings returned from ft_gperror. 

*/ 

res = ft_gperror ( & result, & return_string, & vendor_string, & outcome 

if (res == SUCCESS) { 

if (return_string != NULL) { 

(void)printf("FTAM failure: return_code = %s\n", return_string); 
res = ft_fdmemory(return_string, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, ft_diag); 


/* 

** Print the vendor_code if it exists. 

*/ 

if (vendor_string != NULL) { 

(void)printf("FTAM failure: vendor_code = %s\n", vendor_string); 
res = ft_fdmemory(vendor_string, & outcome); 
if (res != SUCCESS) 

error_handler(outcome, ft_diag); 

} 

} 
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/* 

** Traverse the diagnostic list and print the further_details strings. 
*/ 

while(diag != NULL) { 

(void)printf("FTAM failure: diagnostic number = %d\n", 
diag-error_id); 

if(diag-further_details != NULL) 

(void)printf("FTAM failure: diagnostic = %s\n", 
diag-further_details); 

diag = diag-next; 

} 

exit (-1); 
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Document Types 

Document types define the semantics for classes of files. A document type 
defines the type of file contents by specifying a constraint set and the 
possible data types in the file. Example file types include text files, 
binary files, sequential files, and directories. 

The foil owing table shows information about the parameters in the 
cont_type.contents_info.document-parameters field for FTAM-1, 
FTAM-2, FTAM-3, and INTAP-1 document types. I n all cases, the 
maximum string length is 6144 octets. 


Document 

Type 

String Type 

String Significance 

FTAM-1 

General String (Default 
type) 

Not Significant 


Visible String 

Variable or Fixed 


Graphic String 

Variable or Fixed 


1 a5 String 

Not Significant 

FTAM-2 

Visible String 

Not Significant 


Graphic String (Default 
type) 

Not Significant 

FTAM-3 

Octet String 

Not Significant 

INTAP-1 

Octet String 

Variable or Fixed 


The NBS-9 document type parameter is used only on theft_open() call. 
The attribute names you optionally supply list the attributes you will 
receive for each file in the directory. The default for FI P-UX responders is 
all attributes. Other responders may have different defaults. 


NOTE Refer tothe"FTAM Data Structures"chapter for detailed information on 

setting document types using the Ft_document_type structure. 
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Figure 11-1 


FTAM-1 Document Type 

FTAM-l has only one FADU that contains zero or more text strings. An 
FTAM-1 file contains only one string type, chosen from 
FT_CL_GEN E RAL_STRI N G, FT_CL_I A5_STRI N G, 

FT_CL_GRAPH IC_STRI NG, or FT_CL_VI SI BLE_STRI NG (Figure 11-1) 

FTAM-1 Document Type Structure 



You can only read from or write to the whole data unit (not parts of it). 

FTAM-1 uses the Unstructured constraint set to restrict the file model, 
and therefore uses the Unstructured All access context (Figure 11-2). 
Refer to the "Constraint Sets" and "Access Contexts" sections for detailed 
information. 
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Figure 11-2 FTAM-1 Document Type Restrictions 



NOTE Refer tothe"FTAM Data Structures"chapter for detailed information on 

setting the FTAM-1 document type using the Ft_dt_ftam_l structure. 

FTAM-1 Document Semantics 

The following semantics are mandatory for FTAM-1 document types. 

• FTAM-1 uses restrictions specified by the Unstructured constraint 
set. 

• FTAM-1 does not specify the semantics of the character strings. 

• The characters are from FT_CL_GENERAL_STRI NG, 

FT_CL_I A5_STRI NG, FT_CL_GRAPHIC_STRI NG, or 
FT CL VISIBLE STRING. 
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If the class parameter is not present, the default is 
FT_CL_GENERAL_STRI NG. The character strings may contain 
characters from any of the characters sets registered for use as CO, 
Cl, GO, Gl, G2, or G3 sets, including SPACE. 1 Refer tothe 
"Character Sets" chapter for this list of characters. 

• The stringjength parameter determines the length of maximum 
number of octets in each data element. HP-UX responders accept an 
unlimited stringjength. If stringjength is not present, the character 
strings have a maximum length of 6144. 

• The string_significance parameter determines the exact significance 
of the character stri ngs. Three val ues are supported: 

• FT_SS_NO_SIGNIFICANCE String (data element) boundaries 
are not preserved across transfers. For example, if you create a file 
using eight strings, you may or may not receive eight strings back 
when you read the file. Different FTAM implementations may 
break the file into strings in different ways. 

• FT_SS_FIXED String (data element) boundaries are preserved 
across transfers, and each string is of the size specified in the 
maximum string length parameter. 

• FT_SS_VARI ABLE. String (data element) boundaries are 
preserved across transfers, and the length of each string is less 
than—or equal to—the size specified in the maximum string 
length parameter. 

FTAM-2 Document Type 

FTAM-2 contains zero or moreFADUs, each of which contains zero or 
moretext strings. For FTAM-2, you can have any number of FADUs and 
any amount of data (Figure 11-3). The data units are distinct. For 
example, if you send five data units and ask for them back, you will 
receive five distinct data units in return. 


1. Registered in the I nternational Register of Coded Characters Sets 
for use with Escape Sequences 


Chapter 11 


433 




Document Types and Constraint Sets 

Document Types 


Figure 11-3 FTAM-2 Document Type Structure 

Root FADU 



FTAM-2 uses the Sequential Flat constraint set to restrict the file model, 
and therefore uses either the U nstructured All or FI at Al I access context 
(Figure 11-4). 

Refer to the "Constraint Sets" and "Access Contexts" sections for detailed 
information. 
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Figure 11-4 FTAM-2 Document Type Restrictions 



NOTE Refer tothe"FTAM Data Structures"chapter for detailed information on 

setting the FTAM-2 document type using the Ft_dt_ftam_2 structure. 

FTAM-2 Document Semantics 

The following semantics are mandatory for FTAM-2 document types. 

• FTAM-2 uses the restrictions specified by the Sequential Flat 
constraint set. 

• FTAM-2 does not specify the semantics of the character strings. 
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Document Types and Constraint Sets 

Document Types 


• If the class parameter is not present, the default is 
FT_CL_GRAPH IC_STRI NG. The character strings may contain 
characters from any of the characters sets registered for use as GO, 
Gl, G2, or G3 sets, including SPACE. 1 Refer to the "Character Sets” 
chapter for this list of characters. 

• The stringjength parameter determines the maximum number of 
octets in each data element. HP-UX responders accept an unlimited 
stringjength. If the stringjength parameter is not present, the 
character strings are unbounded. 

• The string_significance parameter determines the exact significance 
of the character strings. OnlytheFT_SS_NO_SIGNIFICANCE value 
is valid. The character string boundaries are not preserved when you 
store the file and do not contribute to the document semantics. 

FTAM-3 Document Type 

FTAM-3 has only one FADU that contains zero or more binary octet 

strings (Figure 11-5). 

FTAM-3 Document Type Structure 



FTAM-3 uses the Unstructured constraint set to restrict the file model, 
and therefore uses the Unstructured All access context (Figure 11-6). 
Refer to the "Constraint Sets" and "Access Contexts" sections for detailed 
information. 


1. Registered in the I nternational Register of Coded Characters Sets 
for use with Escape Sequences 
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Figure 11-6 


FTAM-3 Document Type Restrictions 



NOTE Refer tothe"FTAM Data Structures"chapter for detailed information on 

setting the FTAM-3 document type using the Ft_dt_ftam_3 structure. 

FTAM-3 Document Semantics 

The following semantics are mandatory for FTAM-3 document types. 

• FTAM-3 uses the constraints specified by the Unstructured 
constraint set. 

• FTAM-3 does not specify the semantics of the binary strings. 

• Each binary string contains octets of any value from 0 to 255. 
FTAM-3 does not constrain the meanings of these values. 

• The default class parameter is FT_CL_OCTET_STRI NG. 

• The stringjength parameter determines the length of each binary 
string. FIP-UX responders accept an unlimited stringjength. If the 
stringjength parameter is not present, the binary strings are 
unbounded. 
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Document Types and Constraint Sets 

Document Types 


• The string_significance parameter determines the exact significance 

of the character stri ngs. Three val ues are supported: 

• FT_SS_N 0_SI GNIFI CAN CE - the stri ng or data element 
boundaries are not preserved across file transfers. For example, if 
you create a file using eight strings, you may or may not receive 
eight strings back when you read the file. Different FTAM 
implementations may break the file into strings in different ways. 

• FT_SS_FIXED - the string boundaries are preserved across 
transfers and each string is of the size specified in the maximum 
string length parameter. 

• FT_SS_VARI ABLE - the string boundaries are preserved across 
transfers and the length of each string is less than or equal to the 
size specified in the maximum string length parameter. 

INTAP-1 Document Type 

I NTAP-l has only one FADU that contains zero, one, or more records. 
Each record consists of octets of any value from 0 to 255. Figure 11-7 
shows the I NTAP-l document type structure. 

I NTAP-l uses the Unstructured constraint set to restrict the file model, 
and therefore uses the Unstructured All (U A) access context. Refer to the 
"Constraint Sets" and "Access Contexts" sections for detailed 
information. 

Refer tothe "FTAM Data Structures"chapter for detailed information on 
setting the I NTAP-l document type using the Ft_dt_intap_l structure. 

INTAP-1 Document Type Structure 


unstructured 


root node 


data uni 

t 




record 

record 

record 







* 

★ 

* 

* 

* 

* 


* record-element (data element) 
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Figure 11-8 


INTAP-1 Document Semantics 

The following semantics are mandatory for I NTAP-1 document types. 

• An I NTAP-1 document consists of one file access data unit, which 
consists only of zero, one, or more records. The order of these records 
is significant. 

• Each record consists of octets of any value from 0 to 255. The meaning 
attached to these values is not constrained by the document type. 

• There are no size or length limitations imposed by this definition, 
except for those specified here. Each record is of a length determined 
by the number of octets given by the maximum-record-length 
parameter. If this parameter is not present, the default is that the 
length of the records is unbounded. If the value of the 
record-significance parameter is variable, or if the parameter is not 
present, the length of each record is less than or equal to the length 
given in the maximum- record-length parameter. If the value is fixed, 
the length of each record is exactly equal to the length given. 

NBS-9 Document Type 

TheNBS-9 document type models directories. Each NBS-9 document 

(directory) has only one FADU that contains zero or more data 

elements. (Figure 11-8). 

NBS-9 Document Type Structure 



NBS-9 uses the Unstructured constraint set to restrict the file model, 
and therefore uses the Unstructured All access context (Figure 11-9). 
Refer to the "Constraint Sets" and "Access Contexts" sections for detailed 
information. 
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Figure 11-9 NBS-9 Document Type Restrictions 



NOTE Refer tothe"FTAM Data Structures"chapter for detailed information on 

setting the NBS-9 document type using the Ft_dt_nbs_9 structure. 

NBS-9 Document Semantics 

The following semantics are mandatory semantics for NBS-9 document 

types. 

• NBS-9 uses the Unstructured constraint set. 

• Each data element contains the attributes of one file. 

• The attribute_names parameter is only used on the open call. It 
denotes the set of attributes to be returned for each file in the 
directory. If this parameter is not present on the open call, the default 
isto return all attributes. 

• According to the NIST Phase 111 agreements, responders only need to 
return the filename attribute. Flowever, FIP-UX responders return all 
attributes as specified in the attribute_names parameter supplied on 
the open call. 
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Table 11-1 


• The foil owing table describes the legal operations on NBS-9 
documents: 


Legal Operations for the NBS-9 Document Type 


Standard (specified by the 
NIST agreements) 

HP-UX FTAM Supports these 
Additional Value-Added 
Operations 

select 

create 

open 

delete 

read 

read attri butes 

close 

change attributes 

deselect 
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Constraint Sets 

Every application needs a specific set of file structures, and any real 
system is likely to support only a limited range of file types, with 
restrictions on the ways you can modify files. Constraint sets express 
these limitations by restricting the foil owing items. 

• Range of allowable file structures 

• Ways in which basic access actions can modify the structure 

Constraint sets restrict (reduce) the file model. These sets help you 
efficiently model the type of file you are accessi ng. 

The constraints sets supported by HP-UX FTAM are Unstructured and 
Sequential Flat. 

Unstructured Single, un-named data unit 
Sequential Flat Series of un-named data units 

Each constraint set consists of the foil owing items. 

• A statement of the intended field of application 

• A constraint set descriptor for reference in documentation 

• Constraint set identifier for reference in the FTAM protocol 

• Constrai nts on the node names 

• Set of valid file access actions 

• Qualified actions when writing tothefile 

• Set of file access contexts i n which the fiIe can be read 

• State of the file when created 

• FADU located immediately after the file is opened 

• Definitions of "beginning of file" and "end of file" 

• Manner in which you read from or write to the whole file 

• General constraints on how you can modify the structure 
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• Special semantics of specific file access actions 

• Allowable FADU identity forms for each of the file access actions 

Access Contexts 

Each constraint set contains a list of available access contexts which 
allow you to further restrict the file structure view during read 
operations. The Access Contexts are Unstructured All Data Units(UA) 
and Flat All Data Units (FA). 

For FTAM-1, FTAM-3, and INTAP-1, only the UA access context is 
available. For FTAM-2, both UA and FA are available. If you use the UA 
access context when transferring FTAM-2 files, the file simplifies to an 
FTAM-1 file; the node descriptor information does not transfer. 


NOTE Refer tothe"FTAM Data Structures"chapter for detailed information on 

setting access contexts using the Ft_access_context structure. 


Unstructured All (UA) FT_UNSTRUCTURED_ALL_DATA_UNIT 

S Only the data elements in the data unit 
(from the addressed FADU) transfer. 

Flat All (FA) FT_FLAT_ALL_DATA_UNITS Node 

descriptor information and data elements 
from the data unit (from the addressed 
FADU) transfer in the order that they are 
stored. 
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Unstructured Constraint Set 

The unstructured constraint set applies to files that you can transfer or 
access in whole, or extend; partial access is not available. 

Refer to the foil owing list for applicable basic constraints. 


Constraint Set Name 
Constraint Set Identifier 

Node Names 

Available File Access 
Actions 

Qualified Actions 

Avai Iable Access Contexts 

Creation State 

Location After Open 

Beginning of File 

End of File 

Read Whole File 

Write Whole File 


Unstructured 

ISO Standard 8571 constraint-set (4) unstructured (1) 
(ASN.l syntax for an identifier) 

None 

FT_FA_ERASE 

FT_FA_EXTEND 

FT_FA_READ 

FT_FA_REPLACE 

None 

FT_UNSTRUCTURED_ALL_DATA_UNITS (UA) 

Root node with an empty data unit 
FT_FI RST 
Not applicable 
Not applicable 

Read in access context UA with a FADU identity of 
FT_FI RST 

Transfer a single data unit (without a node descriptor) with 
a FADU identity of FT_FI RST and an FT_FA_RE PLACE file 
access action 
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Additional constraints on the Unstructured constraint set are as follows. 


Structural Constraints All actions in the unstructured constraint set result in a 

structure with a root node that has a data unit (although this 
data unit may be empty). 

Action Constraints The FT_FA_ERASE action yields a root node with an empty 

data unit. 

Identity Constraints TheFADU identity is always FT_FI RST. Use this form of FADU 

identity with all permitted file actions. 

Sequential Flat Constraint Set 

The Sequential Flat constraint set applies to files that arestructured 
into a sequence of individual FADUs. You can access specific FADUs in 
the files by specifying their individual position in the sequence. Refer to 
the foil owing list for applicable basic constraints. 


Constraint Set Name Sequential Flat 

Constraint Set Identifier ISO Standard 8571 constraint-set (4) sequential-flat (2) 

(ASN.l syntax for an identifier) 

Node Names None 

File Access Actions FT_FA_ERASE 

FT_FA_LOCATE 
FT_FA_I NSERT 
FT_FA_READ 

Qual ified Acti ons N one 

Available Access Contexts FT_F LAT_ALL_DATA_U NITS (FA) 

FT_UNSTRUCTURED_ALL_DATA_UNITS (UA) 

Creation State Root node without an associated data unit 

Location After Open Root node 

Beginning of File Root node 
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End of File No node selected. FT_PREVI OUS gives last node in 

sequence; FT_CURRENT and FT_NEXT give an error 

Read Whole File Read in access context FA or UA with FADU identity of 

FT_BEGI N 

Write Whole File T ransfer the series of leaf FADU s which would be generated 

by reading the wholefilein access context FA; perform the 
transfer with a FADU identity of FT_E N D and an 
FT FA INSERT file access action 


Additional constraints on the Sequential Flat constraint set areas 
follows: 


Structural Constraints The root node does not have an associated data unit. All 

children of the root node are leaf nodes and have an associated 
data unit. All arcs from the root node are of length one. 

Action Constraints You can use FT_FA_I NSERT only at the end of a file, with 

FADU identity set to FT_END. The location following an 
FT_FA_I NSERT action is FT_END. You can erase only at the 
root node to empty the file, with FADU identity set to 
FT_BEGI N. The result is a solitary root node without an 
associated data unit. 


Identity Constraints The FADU identity associated with the file action is FT_BEGI N, 

FT_E N D, FT_F IRST, or FT_N EXT. The al lowable actions are as 
follows. 


FT_FA_LOCATE 
FT FA READ 


FT_FA_I NSERT 
FT FA ERASE 


Actions are valid for each FADU identity 
on the whole file and on all leaf nodes. 

Actions are valid for the whole file at 
FT_BEGI N. Actions are valid for leaf 
nodes at FT_FI RST and FT_NEXT. 
Actions are not valid at FT_END. 

Actions are valid on the leaf node with the 
FT_END FADU identity. 

Actions are valid on the whole file only 
with the FT_BEGI N FADU identity. 
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Character Sets 

Former Intro... Change 


Former Intro... Change 

This chapter defines the avail able character sets for the HP FTAM/9000 
product. 

All numbers are in decimal notation. 


IA5String The characters availablefor the I A5String are all 

characters with ordinal values between 0 and 127, 
inclusive. The exceptions are the characters with 
ordinal values 14 and 15. 


General String The characters availablefor the General String are 
all characters with ordinal values between 0 and 
255, inclusive. 

Graphicstring The characters availablefor the Graphicstring are 
all characters with ordinal values 

• between 32 and 126, inclusive, and 


• between 160 and 255, inclusive. 


Additionally, the characters 27, 142, and 143 used 
within escape sequences are available. 

VisibleString The characters availablefor the VisibleString are 
all characters with ordinal values between 32 and 
126, inclusive. 
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Access Context A set of 

restrictions that dictates how the 
information in a file is accessed; 
you can specify access contexts 
only when reading a file. 

Activity Attri butes Attri butes 
that define the properties that 
exist only while a specific FTAM 
connection is being used; these 
attributes are not part of the file. 

Application Entity A uniquely 
identified component of your 
application program that 
associates it with OSI; may be an 
FTAM initiator or FTAM 
responder. 

Application Interface Your 
means of accessing the FTAM 
services (e.g., ft_select()). 

Application Service Element 
(ASE ) Any of theservices provided 
to you in the Application layer of 
the OSI model (e.g., FTAM and 
ACSE). 

Association An I SO term, 
synonymous with "connection." 

Association Control Service 
Element (ACSE) An OSI layer 
seven protocol that provides 
association establishment, abort, 
and association termination. 


Attribute I nformation that states 
a property of a file and takes a set 
of defined values, with each value 
having a defined meaning. 

connectionid A unique 
identifier of a connection for the 
duration of that connection. 

Constraint Set A set of 

restrictions that specify the 
allowable file structures and the 
ways in which access actions can 
modify the structures. 

Context Free (CF) Function A 

function that does not depend on 
the use of other FTAM functions. 

Context Sensitive (CS) 
Function A function that depends 
on the use of other FTAM 
functions; you must call context 
sensitive functions i n a specific 
order. 

Data Control Block (DCB) 

Data structures used for passing 
information between user 
application programs and FTAM 
applications entities. The DCBs 
vary, depending on the function 
call. 
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Data Element The smallest piece 
of data whose identity is preserved 
when transferred by the 
Presentation Service. A data 
element may convey file contents 
information or protocol control 
information. 

Data Unit (DU) The file unit that 
contains the actual file contents; a 
data unit may contain file 
structuring information or data 
elements. 

Document Type The 

specification that defines the type 
of file contents by specifying the 
allowable constraint sets. 

Empty File An FTAM file that 
contains only a root node with no 
associated data unit or node name. 

Event The synchronous or 
asynchronous invocation of an 
FTAM function. 

Event Name A value used to 
uniquely define an event; returned 
on asynchronous calls. 

FADU Identifier A means of 
identifying the FADU; location is 
the only valid value. 


File Access The inspection, 
modification, replacement, or 
erasure of a file's contents or a 
portion of it. 

File Access Data Unit (FADU) 

The smallest unit of the file access 
structure on which you can 
transfer, delete, extend, replace, or 
insert; contains zero or more data 
unit; each FTAM file consists of 
one or more FAD Us. 

File Attribute The name and 
other identifiable properties that 
describe a file, excluding file 
contents. 

File Contents A file's data units, 
node names, and structuring 
information that you can 
manipulateduringthe FileOpen 
regi me. 

File Management The creation 
and deletion of files; the inspection 
or manipulation of file attributes. 

File Model A view of a file's 
structure. 

File Protocol Data Unit 
(FPDU) The blocks of information 
transferred between FTAM 
initiators and FTAM responders. 
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File Service User The portion of 
the application entity that invokes 
theFTAM service. 

File Transfer A function that 
moves a part or the whole of a file's 
contents between open systems. 

File Transfer, Access and 
Management An OSI layer seven 
protocol that allows peer-to-peer 
file transfer, record access, and file 
management. 

FTAM See F ileTransfer, Access 
and Management 

ftam_initThe executable name 
for an HP-UX FTAM initiator; 
sends your request to an FTAM 
responder. 

FTAM Protocol Machine 
(FPM) The protocol followed by 
FTAM to accomplish filetransfer, 
access, and management. 

ftam resp The executable name 
for an HP-UX responder; daemon 
process that provides the interface 
for the HP-UX filesystem (real 
filestore) to the FTAM VFS. 

Grouping A collection of FTAM 
functions that are transferred as a 
single FPDU. 


High Level Service (HLS) A 

function that performs a sequence 
of low level functions, thereby 
eliminating the need to cal I the low 
level functions individually. 

Indication Notification that a 
request arrived at its destination; 
notification that information is 
available. For example, a connect 
indication occurs when an FTAM 
responder receives your connect 
request (ft_connect()). 

Initial Configuration Store 
(ICS) The database that stores the 
initial OSI network configuration. 

I nitiator The entity that submits 
requests on your behalf; when you 
call a function, the initiator sends 
your request to an FTAM 
responder. 

International Organization for 
Standards (I SO) The U nited 
Nations body that conducts the 
balloting and ratification 
procedures for i nternati onal 
communications standards. 

Logging A diagnostic tool used to 
record significant network events; 
logging is always enabled whilethe 
network is operational. 
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Low Level Service (LLS) A 

function that provides the lowest 
level of service for the MAP 3.0 
application interface; a LLS does 
not contain a sequence of other 
calls. 

Manufacturing Automation 
Protocol (MAP) A seven layer 
communications specification; 
allows multi vendor communication 
among factory automation 
equipment without custom links. 

Network Service Access Point 
(NSAP) An addressable point in 
the Network layer that provides 
services to the Transport layer; 
identified by a unique val ue that 
allows network layers to identify 
the connection to its peer. 

Node The elementary component 
from which a FADU tree is built. 

Node Name A name used to 
locate a node that is part of the 
structuring information contained 
in a FADU. 

Note (an event) To indicate that 
a request was serviced and its 
outcome is available. For example, 
issuing an em_wait call is asking 
for the event that was noted for the 
longest period of time. 


Open Systems Interconnection 
(OSI) A set of standards that 
define the seven layers of 
communication protocols for a 
network; I SO defines these 
standards. 

Packet A unit of transmitted data, 
with a fixed maximum size. 

Presentation Address An 

address used to communicate with 
other systems and processes; is 
unique within the network. 

Presentation Service Data Unit 
(PSDU) The actual Presentation 
layer data transmitted to the peer 
Presentation layer. 

Protocol A formalized set of rules 
for network communication. 

Real FileThe actual file, 
including its name and attributes, 
that is mapped to the VF S. 

Real Filestore A collection of 
actual files, including their names 
and attributes, that is mapped to 
the VFS. 

RegimeThe period during which 
you can call a specific set of FTAM 
functions; the regime determines 
the activities that can occur at a 
given time and therefore, creates 
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the rules (protocols) for the FTAM 
state machine. (For example, the 
Data Transfer regime allows 
reading or writing of the file.) 
Regimes are nested. 

Responder The entity that 
receives and services an initiator's 
request; if applicable, the 
responder returns a response; the 
responder interacts directly with 
the virtual filestore. 

Sequential Flat Constraint Set 

A constraint set that generates an 
access structure that 

• consists of two levels (levels zero 
and one), 

• may have data units at only the 
leaf nodes, and 

• has no data unit at the root node. 

Service Provider Process 
(SPP) See "Application Entity." 

State See "Regime." 

Threshold The number of 
functions (within a set of grouped 
functions) that must change 
regimes for the enti re group to be 
successful. 

Tracing A diagnostic tool that 
records specific events on 
individual HP OSI Transport 


Services subsystems. Tracing 
degrades system performance and 
thus, is not always enabled. 

Unstructured Constraint Set A 

constraint set that contains a 
single root node with a data unit; 
nofilestructure information is 
available. 

Virtual Filestore (VFS) An 

abstract model for describing files 
and their attributes, and the 
possible actions on them; provides 
a uniform interface to all real file 
systems. 
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Access Contexts, 40, 90, 443 
Access Control, 92 
Defined Constants, 94 
Accessing FTAM Files, 272 
action_result, 341 
ActivateAE, 254 
Activity Attributes, 39 
AE, 37 

Ae_dir_name, 75 
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Ft_file_ ac ti° ns , 138 
Ft_file_l°ck, 111 
F t_fi I e_p ass w° r ds, 140 
Ft_file_st a tus, 141 
Ft_filename, 143 
Ft_function a l_units, 144 
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Ft_output, 156 
Ft_processing_mode, 148 
Ft_qos, 149 
Ft_service_d a ss, 150 
Ft_single_file_pw, 155 
Ft_structure_id, 121 
F t_xxx_out_dcb, 157 
lnout_dcb, 156 
lnput_dcb, 160 
Local_event_name, 163 
P_ a ddress, 164 
D a t a T r a nsfer 
Cancel, 328 
End, 324, 326 
ft_ed a t a (), 324 
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ReceiveC a ncel lndic a tion, 330 
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FT_PM, 148 
FT_SC, 150 
Delete Files, 128 
Delete Files (HLCF), 242 
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